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"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-repoThe 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.largeThe 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-jsonLike 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