API keys for agents

How is a key's scope decided?

Per Sandboxer's API keys docs, a request is allowed only when both of these hold:

1. its action is in the key's actions, such as exec, file.read or sandbox.create;
2. its target sandbox is one of the key's sandboxes, or in one of its environments.

Everything else is denied.

sbx api-key create one-sandbox --sandbox <sandbox-id> --actions sandbox.read,exec,file.read --ttl 7d

Which presets are there?

A key keeps the actions it was created with, even if a preset gains actions later.

What about the key inside a sandbox?

Every sandbox gets SANDBOXER_TOKEN for the SDK and CLI calls it makes about itself. The in-sandbox key section lists what it can do. It can't create or delete sandboxes, save snapshots, or read or change your account. If code in a sandbox needs more, pass it a key of its own with only the actions it needs and a short --ttl.

How do you rotate or revoke a key?

Sandboxer stores only a hash of each key, and shows the full secret once, when you create or rotate it. You can rotate or revoke a key from the dashboard or the CLI. Its usage stays readable after you revoke it, including which sandboxes it created.

Which actions can a key have?

The API keys docs list each action a key can carry. The main ones:

• sandbox.create, sandbox.read, sandbox.update, and the stop, resume, fork and delete calls;
• exec to run commands, and file.read and file.write for files;
• ssh for SSH, scp and port forwarding, host to host ports, and desktop for the desktop and browser streams;
• agent.prompt to prompt, steer or interrupt an integrated agent;
• snapshot.read and snapshot.write, and environment.read and environment.write for environments and secrets.

Creating keys needs a browser session or a key with the admin preset, so an agent holding a narrow key can't mint itself a wider one.