TIDE
Get started

Docs · Reference

CLI reference

Every mat command. Commands print text meant for people; add --json for output meant for programs. Progress and confirmations go to standard error, so ID=$(mat create) captures only the ID.

CLI referenceMenu

Global options and setup

Options for every command

--json
Print machine-readable JSON instead of text. Commands that list things print one JSON object per line.
--help, -h
Show help for mat or any command.
--version, -V
Print the version.

Environment

MATRYOSHKA_API_URL
With MATRYOSHKA_API_KEY: the API to use, instead of the saved sign-in. Both must be set.
MATRYOSHKA_API_KEY
With MATRYOSHKA_API_URL: an API key (mk_…) or session token (ms_…).
MATRYOSHKA_CA_FILE
A PEM file of extra CA certificates to trust besides Mozilla's roots, for networks that inspect TLS. The system trust store is not used.
XDG_CONFIG_HOME
Where the saved sign-in lives: $XDG_CONFIG_HOME/matryoshka/credentials.json, or ~/.config/matryoshka/credentials.json. The file is readable only by you.

Exit codes

mat exit codes
CodeMeaning
0Success.
1The API refused the request, or could not be reached. The message says why.
2Bad arguments or missing setup, such as not being signed in.
Nmat exec, mat logs and mat shell exit with the remote command's own code, or 128 + the signal that ended it.
130You detached from mat exec with a second Ctrl-C. The command keeps running.

Signing in and your account

mat login

Sign in. mat shows a code; you confirm it in the dashboard, and the session lasts a week.

usage
mat login --url URL [--api-key]

Options

--url URL
The API address, starting with https://. The dashboard's address works too, since it serves the API under /v1.required
--api-key
Use an API key instead, read from standard input (for CI and programs). The key is checked before it is saved.

PrintsThe code and the page to confirm it on, then when the session expires and where it was saved.

example
mat login --url "$MATRYOSHKA_API_URL"To sign in, open this page and confirm the code KQTR-WMZD:  https://…/cli?code=KQTR-WMZDSigned in until 2026-11-06 09:12 UTC.Saved to /home/you/.config/matryoshka/credentials.json
  • mat never opens a browser; open the page yourself. The code is valid for 10 minutes.
  • With --api-key, paste a key that starts with mk_ and press Enter. It never appears in your shell history.

mat logout

End this session and forget the saved credentials.

usage
mat logout
  • With an API key saved, logout only forgets it; the key stays valid until you revoke it in the dashboard.

mat whoami

Show who you are signed in as, and your account's limits and use.

usage
mat whoami
example
mat whoamiaccount	acct-5d2e8a41c09b7f36user	Ada Lovelace <ada@example.com> via githubrunning	1 of 10sandboxes	3 of 50memory	10240 of 204800 MiB
  • With an API key, the user line reads (API key).
  • sandboxes and memory count every sandbox not deleted, paused ones included. running counts sandboxes creating, running, resuming or pausing.

mat billing

Show billing status and this month's usage in hours per size.

usage
mat billing [checkout|portal]

PrintsA status line, then size, running hours and paused hours for every size.

example
mat billingstatus	active, pay as you gousage in 2026-10 (hours)size	running	pausedsmall	0.00	0.00medium	41.25	310.50large	0.00	0.00
  • Paused hours include stopped time; both are billed as storage. The month is the calendar month in UTC.

mat billing checkout

Print the URL of a Stripe Checkout page to add a payment method and subscribe.

usage
mat billing checkout
  • Needs a signed-in session, not an API key. Open the URL yourself.
  • Refused if the account already has a subscription; use mat billing portal instead.

mat billing portal

Print the URL of Stripe's billing portal, for cards, invoices and cancelling.

usage
mat billing portal
  • Needs a signed-in session, not an API key. Works once a payment method was added.

Sandboxes

mat create

Create a sandbox and print its ID once it runs.

usage
mat create [--size SIZE] [--keep-awake] [--idle-minutes N] [egress options] [--secret NAME]…

Options

--size small|medium|large
The size preset.default medium
--keep-awake
Never pause it automatically when idle.
--idle-minutes N
Minutes without activity before it is paused, 1 to 1440.default 10
--egress open|restricted|none
Where the sandbox may connect. New sandboxes default to open.
--allow DOMAIN
With --egress restricted: allow DOMAIN (exactly that name) or *.DOMAIN (its subdomains).repeatable
--no-essentials
With --egress restricted: leave out the essentials (package registries, GitHub, model APIs).
--secret NAME
Attach a brokered secret by name.repeatable

PrintsThe new sandbox's ID on standard output (so ID=$(mat create) works); progress goes to standard error. With --json, the whole sandbox.

example
mat create --size smallCreating a small sandbox...sb-4f1c9e27a0b3d5c86e12
  • When no host has room right now, the create may wait up to a minute before it answers.

mat ls

List your sandboxes, one line each.

usage
mat ls

PrintsOne tab-separated line: ID, status, size, idle setting (idle 10m, or awake), egress (open, none, or restricted: and its domains; (pending) until the host confirms it), attached secrets (- for none), created time, and restarted TIME after a cold boot. With --json, the sandbox object from the API.

example
mat lssb-4f1c9e27a0b3d5c86e12	running	small	idle 10m	open	-	2026-10-30 09:12sb-9a03be5c71d2f4e86b10	paused	medium	awake	restricted:essentials	ANTHROPIC_API_KEY	2026-10-29 16:40
  • Never wakes a sandbox.

mat status

Show one sandbox.

usage
mat status SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

PrintsOne tab-separated line: ID, status, size, idle setting (idle 10m, or awake), egress (open, none, or restricted: and its domains; (pending) until the host confirms it), attached secrets (- for none), created time, and restarted TIME after a cold boot. With --json, the sandbox object from the API.

  • Never wakes a sandbox.

mat set

Change a sandbox's idle, egress or secret settings. Options you leave out stay as they are.

usage
mat set SANDBOX [--keep-awake true|false] [--idle-minutes N] [egress options] [--secret NAME… | --no-secrets]

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

Options

--keep-awake true|false
true never pauses it automatically; false allows it again.
--idle-minutes N
Minutes without activity before it is paused, 1 to 1440.
--egress open|restricted|none
Where the sandbox may connect. New sandboxes default to open.
--allow DOMAIN
With --egress restricted: allow DOMAIN (exactly that name) or *.DOMAIN (its subdomains).repeatable
--no-essentials
With --egress restricted: leave out the essentials (package registries, GitHub, model APIs).
--secret NAME
Make these the attached secrets, replacing the current ones.repeatable
--no-secrets
Detach every secret. Cannot be combined with --secret.

PrintsOne tab-separated line: ID, status, size, idle setting (idle 10m, or awake), egress (open, none, or restricted: and its domains; (pending) until the host confirms it), attached secrets (- for none), created time, and restarted TIME after a cold boot. With --json, the sandbox object from the API.

example
mat set sb-4f1c9e27a0b3d5c86e12 --egress restricted --allow example.com --allow '*.example.org'
  • --egress restricted sets the whole policy: list every --allow you want each time.
  • --allow and --no-essentials need --egress restricted.
  • An egress change applies to new connections; open ones are not cut.
  • New secrets reach new commands and shells. Commands already running keep the environment they started with.
  • Never wakes a sandbox.

mat pause

Pause a sandbox now: memory and files are saved, nothing runs.

usage
mat pause SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
example
mat pause sb-4f1c9e27a0b3d5c86e12sb-4f1c9e27a0b3d5c86e12 is paused
  • Pausing a paused sandbox does nothing and succeeds. A stopped sandbox cannot be paused.

mat resume

Resume a paused or stopped sandbox. Using it with exec, cp, shell, browser or credentials resumes it too.

usage
mat resume SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
example
mat resume sb-4f1c9e27a0b3d5c86e12sb-4f1c9e27a0b3d5c86e12 is running

mat rm

Delete a sandbox with its files, its memory and its snapshots.

usage
mat rm SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
example
mat rm sb-4f1c9e27a0b3d5c86e12sb-4f1c9e27a0b3d5c86e12 is deleted
  • This cannot be undone. Copy out what you want to keep first.
  • A pause, resume or create in progress finishes first. If the host does not confirm at once, the sandbox shows deleting and we finish the deletion in the background.

Commands, files and connections

mat exec

Run a command, stream its output, and exit with its exit code.

usage
mat exec SANDBOX [--cwd DIR] [-e KEY=VALUE]… [--detach] -- COMMAND [ARG]…

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
COMMAND [ARG]…
The program and its arguments, after --. Passed as-is, never through a shell; for shell syntax run sh -c '…'.required

Options

--cwd DIR
Working directory.default /workspace
-e, --env KEY=VALUE
Set an environment variable.repeatable
--detach
Start the command, print its exec ID and return without waiting.
example
mat exec sb-4f1c9e27a0b3d5c86e12 -- python3 -c 'print(6*7)'42mat exec sb-4f1c9e27a0b3d5c86e12 -- sh -c 'npm test && npm run build'
  • The first Ctrl-C interrupts the remote command. A second one detaches and leaves it running; mat prints the mat logs command to reattach.
  • If the connection drops, mat reconnects from the last byte it printed.
  • Commands get no standard input.
  • Resumes a paused sandbox.

mat logs

Reattach to a command's output and follow it until it exits.

usage
mat logs SANDBOX EXEC_ID [--after N]

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
EXEC_ID
The exec ID from mat exec --detach, e.g. ex-7c2d90a1e4b35f8d6a01.required

Options

--after N
Resume from this byte offset of the output.default 0
  • Each command keeps its last 1 MiB of output. If older output was dropped, mat says from which byte it continues.

mat kill

Signal a running command and its children.

usage
mat kill SANDBOX EXEC_ID [--signal interrupt|terminate|kill]

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
EXEC_ID
The exec ID.required

Options

--signal interrupt|terminate|kill
SIGINT, SIGTERM or SIGKILL.default terminate

mat export

Download a file or a whole directory from a sandbox as a gzipped tar archive (/workspace unless --path says otherwise).

usage
mat export SANDBOX [--path PATH] [-o FILE]

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

Options

--path PATH
An absolute path in the sandbox, a file or a directory. Default /workspace.
-o, --output FILE
Where to save it. Default SANDBOX.tar.gz.
example
mat export sb-4f1c9e27a0b3d5c86e12Exporting sb-4f1c9e27a0b3d5c86e12:/workspace...sb-4f1c9e27a0b3d5c86e12:/workspace -> sb-4f1c9e27a0b3d5c86e12.tar.gz (48211730 bytes, gzipped tar)
  • Resumes a paused sandbox, like any file read.
  • Also works for 30 days after your subscription ends, when sandboxes cannot run: the sandbox is resumed only to export, nothing else of yours runs meanwhile, and it is paused again after. The dashboard's Download files button does the same.
  • A download that stops partway fails rather than leaving a cut-off archive.

mat cp

Copy one file between your machine and a sandbox, either way.

usage
mat cp SOURCE DESTINATION

Arguments

SOURCE
A local path, or SANDBOX:/absolute/path.required
DESTINATION
A local path, or SANDBOX:/absolute/path.required
example
mat cp ./app.py sb-4f1c9e27a0b3d5c86e12:/workspace/app.py./app.py -> sb-4f1c9e27a0b3d5c86e12:/workspace/app.py (1832 bytes)mat cp sb-4f1c9e27a0b3d5c86e12:/workspace/out.json ./out.jsonsb-4f1c9e27a0b3d5c86e12:/workspace/out.json -> ./out.json (40961 bytes)
  • One side must be local and the other in a sandbox. A sandbox path is the ID, a colon and an absolute path.
  • Single files up to 1 GiB; no directories. Uploads create missing parent directories, replace the target only once complete, and belong to the agent user.
  • A download is written beside the target and renamed into place, so a failed one never leaves a half-written file.

mat shell

Open an interactive login shell (bash, as agent) in the sandbox.

usage
mat shell SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required
  • Resizing, Ctrl-C and full-screen programs work. mat exits with the shell's exit code.
  • Closing the connection ends the shell. Use tmux inside for sessions that must survive a disconnect.

mat browser

Print a single-use URL for driving the sandbox's Chromium over the Chrome DevTools Protocol.

usage
mat browser SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

PrintsThe wss:// URL on standard output; when it expires on standard error. It works once, within 60 seconds.

example
mat browser sb-4f1c9e27a0b3d5c86e12wss://…/v1/connect/ct_…Single use, valid until 09:31:05 UTC. Example (Playwright): chromium.connect_over_cdp(url)

Network, secrets and credentials

mat egress

Show the sandbox's recent outbound connections and what became of them, oldest first.

usage
mat egress SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

PrintsOne tab-separated line each: time, allowed, denied or failed, the name asked for (- if none), address:port, the reason, the secrets that could be added, and (N times, latest shown) for repeated entries.

example
mat egress sb-4f1c9e27a0b3d5c86e122026-10-30 09:14:51	allowed	pypi.org	151.101.0.223:443	2026-10-30 09:15:02	denied	example.net	93.184.215.14:443	not on the allowlist2026-10-30 09:15:40	allowed	api.anthropic.com	160.79.104.10:443	secret added: ANTHROPIC_API_KEY (3 times, latest shown)
  • The log is kept in memory on the sandbox's host: the last 1000 connections, lost if the host agent restarts.
  • Never wakes a sandbox.

mat activity

Show what keeps a running sandbox from pausing on its own: open connections, requests still waiting for an answer (and where to), recent network traffic or CPU use, or keep-awake.

usage
mat activity SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

PrintsA list of reasons, or that it is idle and roughly when it pauses.

example
mat activity sb-4f1c9e27a0b3d5c86e12sb-4f1c9e27a0b3d5c86e12 is kept awake by:  - 1 open connection: a shell, a running command, a file transfer, the browser or a preview  - waiting for an answer from api.anthropic.com
  • Never wakes a sandbox. What keeps it awake is yours to manage: close shells and connections you no longer need.

mat credentials

List the credentials stored in a sandbox: names and places, never values.

usage
mat credentials SANDBOX

Arguments

SANDBOX
The sandbox ID, e.g. sb-4f1c9e27a0b3d5c86e12.required

PrintsOne tab-separated line each: kind, name, domain (- if unknown), location.

example
mat credentials sb-4f1c9e27a0b3d5c86e12aws_profile	default	-	/home/agent/.aws/credentialsdot_env	OPENAI_API_KEY	-	/workspace/app/.envgithub_cli	octocat	github.com	/home/agent/.config/gh/hosts.yml
  • A best-effort scan of well-known places, not a guarantee.
  • Scanning needs the sandbox, so this resumes a paused one.

mat secret set

Create or replace a brokered secret. The value is read from standard input.

usage
mat secret set NAME --domain DOMAIN…

Arguments

NAME
Also the environment variable the placeholder appears as in sandboxes. Letters, digits and _, not starting with a digit, up to 128 characters.required

Options

--domain DOMAIN
Where the value may be sent: DOMAIN or *.DOMAIN. 1 to 16.required · repeatable
example
mat secret set ANTHROPIC_API_KEY --domain api.anthropic.comPaste the secret value and press Enter:ANTHROPIC_API_KEY saved for api.anthropic.com (attached to 0 sandboxes)
  • On a terminal it prompts; otherwise it reads everything piped in (a trailing newline is dropped).
  • The value is 1 to 8192 bytes of printable ASCII, since it travels in HTTP headers.
  • Replacing a secret updates every sandbox it is attached to.

mat secret ls

List secrets: names, domains, how many sandboxes use each, and when it last changed. Never values.

usage
mat secret ls

PrintsOne tab-separated line each: name, domains, N sandboxes, last changed.

mat secret rm

Delete a secret and detach it from every sandbox.

usage
mat secret rm NAME

Arguments

NAME
The secret's name.required
example
mat secret rm ANTHROPIC_API_KEYANTHROPIC_API_KEY deleted and detached from every sandbox

Snapshots

mat snapshotnew

Save the sandbox's memory and files, and print the snapshot's ID once it is ready.

usage
mat snapshot SANDBOX [--name NAME]

Arguments

SANDBOX
The sandbox ID.required

Options

--name NAME
A label for people, 1 to 64 characters. It need not be unique.

PrintsThe snapshot ID on standard output. With --json, the whole snapshot.

example
mat snapshot sb-4f1c9e27a0b3d5c86e12 --name before-migrationsnap-0b9e4a7c21d85f3e6a14
  • A running sandbox is frozen briefly while its memory is written, then keeps running. A paused sandbox is copied as it is and stays paused.
  • A stopped sandbox has no memory to save. Use it once to boot it, then take the snapshot.
  • A sandbox keeps at most 10 snapshots. Delete one to take another.

mat snapshotsnew

List the sandbox's snapshots.

usage
mat snapshots SANDBOX

Arguments

SANDBOX
The sandbox ID.required

PrintsOne tab-separated line each: ID, status (creating, ready, failed or deleted), name (- for none), disk it holds in MiB, how long the sandbox was frozen (froze N ms), and when it was taken. With --json, the snapshot object from the API.

example
mat snapshots sb-4f1c9e27a0b3d5c86e12snap-0b9e4a7c21d85f3e6a14	ready	before-migration	412 MiB	froze 240 ms	2026-10-30 09:40

mat snapshot rmnew

Delete one snapshot.

usage
mat snapshot rm SANDBOX SNAPSHOT

Arguments

SANDBOX
The sandbox ID.required
SNAPSHOT
The snapshot ID, e.g. snap-0b9e4a7c21d85f3e6a14.required
example
mat snapshot rm sb-4f1c9e27a0b3d5c86e12 snap-0b9e4a7c21d85f3e6a14snap-0b9e4a7c21d85f3e6a14 is deleted
  • A snapshot still being taken cannot be deleted yet. Deleting a deleted snapshot succeeds.

mat restorenew

Roll the sandbox back to one of its snapshots: memory and files.

usage
mat restore SANDBOX SNAPSHOT

Arguments

SANDBOX
The sandbox ID.required
SNAPSHOT
One of this sandbox's snapshots, in the ready state.required
example
mat restore sb-4f1c9e27a0b3d5c86e12 snap-0b9e4a7c21d85f3e6a14sb-4f1c9e27a0b3d5c86e12 is paused at snap-0b9e4a7c21d85f3e6a14; it resumes on its next use
  • Everything the sandbox did since the snapshot is lost. Files and processes go back to how they were.
  • The sandbox ends paused at the snapshot's moment. Its next use resumes it with the processes it had then.
  • The snapshot is kept, so you can restore it again.

mat forknew

Create a new sandbox from a snapshot's files, and print its ID.

usage
mat fork SNAPSHOT

Arguments

SNAPSHOT
The snapshot ID, e.g. snap-0b9e4a7c21d85f3e6a14.required

PrintsThe new sandbox's ID on standard output; progress on standard error. With --json, the whole sandbox.

example
mat fork snap-0b9e4a7c21d85f3e6a14Forking snap-0b9e4a7c21d85f3e6a14...sb-a27c03e9f1b84d56c0e3
  • The new sandbox boots fresh: it has the snapshot's files but none of its processes.
  • It gets the source's size and its idle, egress and secret settings, and a new ID, network address and secret placeholders.
  • It counts as a create: the create rate limit and your quotas apply.