Spawning Orbs

Use amp -ox to run an execute-mode prompt in an orb instead of on your machine. -ox is shorthand for --orb-execute -x. The CLI creates a new thread whose agent runs in an orb on Amp’s servers, prints the thread URL, and exits right away. The agent keeps working after the command returns, so nothing is blocked on your terminal or your computer staying awake:

$ amp -ox "Investigate why the latest CI run on main failed"
https://ampcode.com/threads/T-…

Open the URL to watch the thread, or continue it from the web, the CLI, or another device. Use amp sync to mirror the orb’s changes back onto your local machine.

Piped input works the same way as with -x. The CLI includes stdin in the prompt it sends to the orb:

$ git diff main | amp -ox "Investigate any DB perf risks in this diff, report back to me on Slack"

Use the Interactive TUI

Use --executor orb to open the TUI with a new orb thread selected:

$ amp --executor orb

Amp waits for your first prompt before it creates the thread and starts the orb. You can edit the prompt, choose a mode, and change the project in the TUI before you submit it.

If the current directory does not match an Amp project, the TUI warns you and the orb starts without a repository. You can select a project in the TUI before submitting your first prompt.

The executor can also be a local process or one of your runners:

$ amp --executor local
$ amp --executor runner:my-runner-id

The same flag works in execute mode. For example, amp -x "Update the README" --executor orb is equivalent to amp -ox "Update the README".

Choosing the Project

An orb starts from a project. By default the CLI looks at the Git remotes of the current directory and picks the matching project. Pass --project to choose one explicitly, for example when you run the command outside a checkout or the directory matches more than one project:

$ amp -ox "Update the README" --project my-org/my-repo

The value can be an Amp project (namespace/name), a GitHub owner/repo, or a repository URL. If no project matches and you do not pass --project, the CLI warns and starts the orb without a repository.

Orb Size and Thread Options

Pass --orb-size to run the orb on a different size than the project default. See Sizes & Costs for the available sizes.

$ amp -ox "Run the full browser test matrix" --orb-size a1.large

The other options that shape a new execute-mode thread also apply: --mode picks the agent mode, --fast turns on Fast mode, and --title sets the thread title.

Continuing an Orb Thread

Combine -ox with threads continue to send one message to an existing thread. The message runs on that thread’s own orb; the CLI does not attach as the executor. This is a simple way to wake a thread from a CI job or shell script:

$ amp threads continue T-… -ox "The deploy finished, verify the fix in production"
https://ampcode.com/threads/T-…

When continuing a thread, --mode, --project, and --orb-size are ignored because the thread keeps its existing mode, project, and orb.

Streaming Output From an Orb

Add --stream-json to stay attached and receive the orb thread’s events as streaming JSON until the turn ends. The output format is identical to local amp -x --stream-json, so existing consumers work without changes:

$ amp -ox "Summarize the open TODOs in this repo" --stream-json

Like local execute mode, -ox --stream-json archives a new thread when the turn finishes. Pass --no-archive-after-execute to keep it. Without --stream-json, -ox returns before the turn runs and leaves the thread unarchived. --stream-json-input is not supported with -ox; send a single prompt instead.

Non-Interactive Environments

For non-interactive environments, such as scripts and CI/CD pipelines, set your access token in an environment variable:

export AMP_API_KEY=your-access-token-here

Use an access token from Settings, which starts with sgamp_. The CLI rejects the short-lived session token that amp login stores, because it expires within an hour and cannot be refreshed from an environment variable.