---
title: "vakna run: create a box and run a command in it"
description: "Create a box and run a command in it; the box's name goes to stderr."
command: "vakna run"
generated: scripts/generate.ts
verified:
  cli: "0.0.0-mock"
  date: "2026-10-20"
---

`vakna run`: create a box and run a command in it; the box's name goes to stderr.

## Synopsis

```sh
vakna run [box] -- <command>
```

## Flags

| Flag | Default | What it does |
| -- | -- | -- |
| `--rm` | `off` | delete the box when the command exits |
| `--format <format>` | `text` | text, or json: one JSON object per line |
| `--json` | `off` | the same as --format json |
| `-h, --help` | `off` | this help |

## Examples

### Example

```sh
$ vakna run api-2 -- make test
```

```prints
created api-2 · started in 0.41s · cold boot
ran make test · exit 0 0.40s
```

Exit code 0.

### Another example

```sh
$ vakna run --rm -- pytest
```

```prints
created box-1 · started in 0.41s · cold boot
208 passed, 4 failed
ran pytest · exit 1 52.11s
deleted box-1
```

Exit code 1.

### When it fails

```sh
$ vakna run api-2
```

```prints
vakna: the mock can't open an interactive shell; give a command after --
hint: vakna run --help
```

Exit code 2.

## Exit codes

| Code | Meaning |
| -- | -- |
| 0 | ok |
| 2 | usage: a missing argument, an unknown flag or command |
| 255 | vakna failed under shell, run, try or fork |

## JSON output

With `--format json` (or `--json`) every line is one JSON object. `v` is the format's version; `mocked` marks numbers from the mock.

```sh
$ vakna run api-2 --json -- make test
```

```prints
{"v":1,"event":"created","box":"api-2","id":"sbx_eu1a_01JB83A1B2C3D4E5F6G7H8J9K0","ms":405,"from":"cold","mocked":true}
{"v":1,"event":"ran","box":"api-2","id":"sbx_eu1a_01JB83A1B2C3D4E5F6G7H8J9K0","command":"make test","exit":0,"ms":400,"mocked":true}
```

## Errors

- [`vakna: unknown command, unknown flag or missing argument`](https://vakna.com/docs/errors/usage): Run `vakna <command> --help` and fix the command line it points to.
- [`vakna: a box named <box> already exists`](https://vakna.com/docs/errors/exists): Pick another name, or delete the old box with `vakna delete <box>` first.
- [`vakna: lockdown blocked <host>`](https://vakna.com/docs/errors/egress_blocked): Run `vakna net allow <host>` with the host the error names, then run your command again.

## --help

This page and the help text come from one definition.

```prints
vakna run · create a box and run a command in it; the box's name goes to stderr

usage
  vakna run [box] -- <command>

flags
  --rm               delete the box when the command exits  (default: off)
  --format <format>  text, or json: one JSON object per line  (default: text)
  --json             the same as --format json  (default: off)
  -h, --help         this help  (default: off)

examples
  vakna run api-2 -- make test
  vakna run --rm -- pytest

exit codes
  0    ok
  2    usage: a missing argument, an unknown flag or command
  255  vakna failed under shell, run, try or fork
```