monoceros run

Runs a one-off command in the named workbench and returns its exit code. Brings the container up first if needed; nothing lingers afterward (unlike shell).

monoceros run <name> --in <dir> -- <cmd> [args...]

Use it for build scripts, single CLI calls, health checks, or handing an agent a task. stdio is inherited, so interactive inner commands (claude, psql, …) work just as they do in a shell session.

The -- separator

Everything after -- is the inner command and its arguments, handed straight to the container untouched. The -- is required: without it, Monoceros would try to interpret flags like --help as its own.

Monoceros’ own flags (like --in) go before the --:

monoceros run acme --in projects/web -- pnpm install --frozen-lockfile
#            ^name  ^monoceros flag    ^inner command + its args

Run in a sub-directory with --in

By default the command runs in the workspace folder (/workspaces/<name>), which holds .devcontainer/, home/, data/, and projects/. Most real work lives in a project under projects/, so --in lets you target it directly:

monoceros run acme --in projects/web -- pnpm dev

--in accepts a path relative to the workspace folder (or an absolute path).

A directory that does not exist yet is offered rather than refused:

`projects/shop` does not exist in the container. Create it? (Y/n)

Say no and nothing runs, so a typo does not start a command in the wrong place. This is the shape of the first run for a new app: the directory is the agent’s to create, and it has to be started somewhere. Starting one level up instead is not the same thing, because a language server looks for its markers (package.json, go.mod) in the directory it was started in.

In a script or a pipeline there is nobody to ask, so a missing directory is an error there. Pass --yes (or -y) to have it created without the question.

Why --in beats `cd` yourself

monoceros run acme -- cd projects && pnpm dev does not work: cd is a shell builtin, not a program, and there is no shell between Monoceros and the container. --in wraps the cd for you and keeps the inner command a plain argument list, so arguments with spaces or quotes survive without extra shell escaping. For other builtins (export, source, && pipelines) you still need an explicit shell: monoceros run acme -- bash -lc 'export FOO=bar && env'.

Examples

Run the test suite of a project:

monoceros run acme --in projects/api -- pnpm test

Runs pnpm test inside projects/api/. The exit code is propagated, so this plugs straight into your own scripts or CI.

Start a dev server:

monoceros run acme --in projects/web -- pnpm dev

Because stdio is inherited, you see the live server output and can stop it with Ctrl-C. The first port the workbench exposes is reachable at acme.localhost.

Open an interactive agent in a project:

monoceros run acme --in projects/web -- claude

Drops you into Claude Code with projects/web/ as the working directory - the same as if you had opened a shell and cd-ed there yourself.

Hand an agent a task:

monoceros run acme --in projects/web -- claude "Add a health-check endpoint at /healthz that returns 200 OK"

Claude runs interactively inside the workbench - you watch it work and answer any questions, then keep going with follow-up prompts. --in keeps the long prompt as one clean argument - no nested quoting required. On the first run a browser tab opens once so you sign in to Claude; the session then persists.

Run a database shell against a service:

monoceros run acme -- psql -h localhost -U postgres

No --in needed - psql does not care about the working directory.

Behavior

• Brings the container up first. A quiet devcontainer up runs if the container is not already started; it is a no-op otherwise.
• Exit code is propagated. Whatever the inner command returns, run returns.
• Nothing lingers. Unlike shell, there is no session left behind once the inner command exits.

See also

• monoceros shell - interactive bash session
• monoceros apply - build and start the workbench