abx-common

abx: the shared half

abx addresses the platform: the environments, warm pools and autoscaling groups that sandboxes are claimed from. The sandboxes themselves — creating one, running commands in it, reading its filesystem — are the E2B SDK's job, and that line is the product, not an omission. If the task is "run something in a sandbox", reach for E2B. If it is "there is nowhere to run it yet", or "it will not scale", you are in the right place.

Do this first

abx agent-context        # the whole tool as one JSON document

Every resource, every filter, every column, every write, and the grammar that assembles them. It is generated from the same registry the CLI dispatches on, so it cannot describe a command that does not exist. Reading it once costs less than three --help calls and answers more.

The grammar

abx <resource>                        list
abx <resource> <id>                   get
abx <resource> <id> <sub>             sub-list
abx <resource> <id> <sub> <sub-id>    sub-get

abx create <collection…> -f FILE      make one; it must not exist yet
abx update <item…> -f FILE            change one; it must exist
abx delete <item…>
abx scale <item…> --replicas N        pools only

A verb is read in the first position and nowhere else. Everything after it is an address, which is why abx envs apply is the env called apply and why a name can never collide with a write. Reads have no verb at all.

The address matches the console URL segment for segment, so /clusters/c/envs/e/pools/p and abx envs e pools p --cluster c are the same thing said twice.

Driving an Env over E2B, and the one read that comes first

Sandboxes belong to the E2B SDK, and what that SDK needs and you cannot guess is where the endpoints are: the E2B-compatible API URL, the data-plane domain, and whether the data plane is http or https. Every Env carries its template's documentation, already rendered for the cluster that Env lives on:

abx envs <env> docs

Read it before creating a sandbox against an Env you have not used. It is the only place that knows the endpoints of the cluster you are actually talking to, and the failure it prevents is the quiet one: the SDK pointed at the wrong host, or at e2b.dev, never connects and never says why.

When the document offers more than one way in — the same cluster, another cluster, the public one — take the public one unless you are told otherwise or you can see you are already inside that cluster's network. It is the only path that does not depend on where the caller happens to be running.

The key in that document stays written as ${AGBX_API_KEY}. That is not a missing value: it is your own credential, the one abx is already authenticating with, and the SDK reads the same key from E2B_API_KEY. No rendered document ever carries a live token — for a person's key or an agent's — which is what makes these pages safe to read, print and relay. The console fills the placeholder in for a person reading it there; nothing else should.

Finding a shape — never from memory, never from a document

Anything a command takes is answerable by that command, and asking is the only way to get the answer for the build you are actually talking to. Prose — this file included — is a copy, and a copy of a schema goes stale the first time the schema moves:

abx create envs --help              # the file create takes: example + every field
abx create envs --schema            # …the same body as JSON, refs resolved, no key needed
abx update envs <env> --help        # the same file, plus how to obtain one
abx update envs <env> --schema      # …and the same body as JSON
abx envs <env> pools --help         # …and for a member pool, addressed the same way
abx <resource> --help               # columns, filters, sub-resources, writes
abx envs <env> --editable           # the current values, in exactly that shape
abx agent-context                   # all of it as one JSON document

abx create|update <address> --help is generated from the API schema at build time, so its field list cannot drift from the server you are writing to. When you are about to write a file, that page is the specification; when you are about to change one, --editable is the file to start from.

The image carries the contracts themselves, read-only, for the shapes abx does not own — a sandbox's own create call, for instance:

/opt/agentbox/source/pkg/openapi/native/openapi.yaml  the platform API
/opt/agentbox/source/pkg/openapi/e2b/openapi.yaml     the E2B surface a sandbox speaks
/opt/agentbox/source/sdk/                             this platform's own SDKs
/opt/agentbox/source/cli/src/                         this CLI's source

That is where to look for anything the CLI only uses: the exact fields a sandbox create call accepts are in the E2B spec there, not in a skill. The Python SDK is a third-party package installed in the sandbox, so ask it directly — its signature is the version-matched answer:

python -c "import inspect, e2b; print(inspect.signature(e2b.Sandbox.create))"

Authentication

Two settings are required, resolved as flag → environment → ~/.config/abx/config.json:

That is the whole setup. The endpoint is the console's own address — the one a person types in a browser — and one address reaches every cluster the platform has.

Which header the key travels in follows from that, so there is no scheme to set: the console takes Authorization: Bearer, a cluster API takes AGENTBOX-API-KEY. --auth-scheme is an override for a deployment answering to neither, and is otherwise unnecessary. Console links in output are derived from the endpoint too.

The exception: a sandbox with no network route to the console is configured with --cluster-api (AGENTBOX_CLUSTER_API) pointing at one cluster's own API instead. Everything below about choosing a cluster then does not apply — that address answers for one cluster and refuses any other. You will not choose this; whoever deployed the platform did, and it shows up already set in the environment.

Under the Claude Code plugin the key is in the OS keychain and a hook writes the config file. Do not read that file, echo the key, or pass it on a command line — it is deliberately kept out of the conversation, and putting it back in defeats the arrangement.

abx whoami answers who the key acts as, and — the part worth checking before a write — whether it is an agent key.

abx speaks as one tenant and has no flag to act as another. That is deliberate: acting as somebody means holding their key, not asking yours to pretend. Administrative work across tenants belongs in the console.

Clusters

Management calls are per cluster, and the cluster is chosen per command with --cluster (AGENTBOX_CLUSTER). It is not part of the context: a context names a platform, and that platform may have several clusters, so a default would quietly answer for whichever one happened to be set.

Through a console — the normal case — --cluster reaches any cluster the platform has, and when there is exactly one it is filled in for you.

In the --cluster-api exception above, the address answers for its own cluster and refuses a --cluster naming a different one. That refusal is deliberate: returning the local cluster's rows under another cluster's name is data that is confidently mislabelled, and a reader cannot tell. Treat the refusal as the truth about that sandbox, not as something to work around — there is no route to the other cluster from there.

abx clusters                    # what this deployment can reach
abx envs --cluster <cluster-id> # choose one for this command

Output

Three registers, and the middle one is the default:

• table — a header line, a count, a view: link to the same page in the console where the console has a page for it, and hint: lines naming what to do next. Truncated at 200 rows with the filters that would narrow it.
• --json — the raw API shape. No header, no hints. Use it when piping.
• --csv — flat, for a spreadsheet or cut.

--wide adds the columns held back by default. --filter key=value narrows a list, where key is a column heading — the heading, the filter key and the CSV column are one name on purpose.

You have a shell. Use it: abx envs <env> pools --json | jq, loops, aggregation. That is the point of a CLI over a tool-per-operation surface, and the sandbox you are probably running in has no real credentials in it anyway — the egress sidecar substitutes them on the way out.

Writes, and approval

Do not write the file from memory. Ask the CLI for it:

abx create envs --help                  # create's file: address, example, fields
abx create envs --schema                # the same body as JSON, every ref resolved
abx update envs <env> --help            # the same file, plus how to get one
abx create envs <env> pools --help      # …and the same for a member pool

That page is generated from the API schema, so it lists every field, which are required, and which are fixed at create — it cannot be out of date in the way a copy in a document can. abx agent-context carries the same data as JSON, if you want to read it once rather than per command; --schema is the same body for one address, and it works with no deployment or key, because the shape comes from the build, not the server.

The two verbs are separate words now: create makes one (it must not exist yet), update changes one (it must exist). They take the same file — the file a create wrote is the file an update takes.

update is a PUT of the desired state: a field the file leaves out is a field you are asking to remove. That is why the safe edit is to start from what is there rather than from a blank page:

abx envs demo pools --json                    # find the pool's name
abx envs demo pools demo-1c2gi --editable > pool.json
# edit pool.json
abx update envs demo pools demo-1c2gi -f pool.json

The file is NOT the object --json prints: those keys are nested under spec.*/status.*, the write reads top-level ones, and the ones it does not find are the ones it clears. Piping --json straight into a write is the fastest way to lose state.

abx scale envs <env> pools <pool> --replicas N is the exception: one field, no clearing, and it re-sends the current bounds unchanged. Use it when size is all you are changing — and not at all when the pool's scaling group has autoscaling enabled, where the autoscaler owns the number and the API says so.

An agent key's writes are held for a person to release. The command comes back saying so, with a link. That is not an error to work around: re-run the command after the person has acted.

Three writes are refused outright, with no approval to wait for: issuing an API key, promoting one, and deciding an approval. An agent that could mint a credential could mint one without the agent restriction and leave the gate entirely, and no approval dialog conveys that. The answer is a console link for the person to act on themselves. Do not queue, retry, or look for a flag.

For the same reason, an agent key gets key metadata without key material: abx api-keys lists what exists and which keys are gated, and the token field is absent. A rendered document — an Env's docs, a Template's docs, the setup guide in the console — comes back with ${AGBX_API_KEY} intact rather than a live token, for every caller and not only for you. Relay the document and say where the person's own key goes; there is nothing missing to hunt for.

The refusal and the wait are different answers and the error codes say which: APPROVAL_REQUIRED means a person is about to decide, so re-run it shortly. FORBIDDEN_FOR_AGENT means no approval exists or ever will — stop, and hand over the link.

Errors carry the recovery

A rejection names the valid set and the next command. Read it before reformulating — it usually contains the answer, and a guess costs a round trip.

Where to go next

Read more

The object model