# kosa8 sandbox create

Boot a new sandbox microVM

## Usage

```
kosa8 create [NAME]
```

Boots a sandbox: its own VM, kernel and container engine.

--egress deny and --egress-allow are enforced on the host, in the userspace
network every frame from the VM passes through, so root inside the sandbox
cannot lift them; the same policy is also applied inside the guest. In an
allow-list sandbox DNS is answered by the host, for the listed names only.
--egress-allow '*.example.com' admits every name below example.com, at any
depth, but not example.com itself (list it too if needed); *.com and other
public suffixes are refused. A wildcard is enforced on the host alone: the
in-guest layer cannot resolve one ahead of time, so it steps aside for a
sandbox that has one.
--egress fakenet is for malware analysis: nothing leaves the host, and a
simulated internet there answers every name and connection and records it
(`kosa8 lab net SANDBOX`; see `kosa8 lab --help`).
Refused attempts go to the audit log (see `kosa8 sandbox egress`).

--pcap FILE captures from the first frame, boot included. Every frame the sandbox sends or receives is written, on the host, to a pcapng
file that opens in Wireshark or tshark. The guest cannot see, stop or edit it —
root in the guest included — because the capture is taken where the host's
userspace network reads each frame.

Rotation: FILE is the first segment. At --pcap-max-mb it closes and FILE.2.pcapng,
FILE.3.pcapng... follow; with --pcap-files N the oldest is deleted once N exist,
so the capture never holds more than N × max on disk. --pcap-files 1 keeps one
segment and stops when it is full, deleting nothing. Each closed segment's
SHA-256 is written to the audit log (action sandbox.pcap.segment).

A capture holds everything the guest said in the clear — tokens, cookies, keys
sent without TLS. The files are owner-only; treat them like the secrets they
may contain.

--label CUI marks it with a classification from the org policy's lattice
(UNCLASSIFIED < CUI when no policy defines one). The label is inherited by
every snapshot, restore and fork, limits which host directories may be
mounted (--mount), what egress it may have and where its snapshots may go,
and is recorded in the audit log. See `kosa8 label --help`.

--auto-stop 30m stops it after 30 minutes without use. Use is a request
for it or anything running inside it, so a build left running keeps it
up. --ttl 2h stops it two hours after it was created, in use or not.
--auto-delete 24h deletes it once it has been stopped a day. --ephemeral
deletes it, disk and all, whenever it stops. Change these later with
`kosa8 sandbox lifecycle`.

--gpu hands the sandbox a whole host GPU (Linux hosts with KVM only):
a PCI address such as 0000:01:00.0 (repeatable), any for one free card,
or all for every free card. `kosa8 doctor` on the host lists the cards and
whether each is ready. The card is the sandbox's alone while it runs, and a
sandbox with a GPU cannot be checkpointed, rewound or forked; stopping it
keeps its disk. Give it memory to match the work (--memory).

--backend docker runs the sandbox as a container on Docker Engine under
gVisor instead of a microVM: for hosts that cannot boot one, and GPUs on
machines rented as VMs. Docker must have gVisor's runtime (runsc). With
it, --gpu takes any, all, or a GPU index or UUID as nvidia-smi -L shows.
A container sandbox cannot be checkpointed, rewound or forked yet.

## Flags

| Flag | Type | What it does | Default |
|---|---|---|---|
| `--auto-delete` | duration | delete the sandbox once it has been stopped this long, e.g. 24h (0: never) | `0s` |
| `--auto-stop` | duration | stop the sandbox after this long without use, e.g. 30m (0: never) | `0s` |
| `--backend` | string | vm (the default; on Windows, docker) or docker: a gVisor container on Docker Engine |  |
| `--cpus` | uint | vCPUs | `2` |
| `--disk` | int | data disk in GB, holding images and everything written inside the sandbox (sparse: it costs what is used, not what is declared; default is the plan's) | `0` |
| `--egress` | string | network policy, enforced on the host: any (default), deny (nothing leaves, DNS included), or fakenet (nothing leaves; a simulated internet on the host answers and records everything) |  |
| `--egress-allow` | stringArray | permit outbound traffic only to these hostnames, *.domain wildcards, IPv4 addresses or CIDRs (repeatable); implies deny for everything else | `[]` |
| `--ephemeral` | bool | delete the sandbox, disk and all, whenever it stops |  |
| `--gpu` | stringArray | hand the sandbox a whole host GPU: a PCI address (repeatable), any (one free card) or all (Linux hosts only) | `[]` |
| `--label` | stringArray | classification from the org policy (CUI, "CUI//SP-EXPT//NOFORN"), or KEY=VALUE for any other label (repeatable) | `[]` |
| `--memory` | uint64 | memory in MiB | `1024` |
| `--mount, -v` | stringArray | share a host directory into the sandbox: HOST:GUEST[:ro] (repeatable) | `[]` |
| `--pcap` | string | capture every frame the sandbox sends or receives to this pcapng file, from boot |  |
| `--pcap-files` | int | segments kept on disk; the oldest is deleted beyond this (1 = stop when full) | `8` |
| `--pcap-max-mb` | int64 | size at which a capture segment closes and the next begins, in MiB | `64` |
| `--template` | string | start with a template's image (see kosa8 template build) |  |
| `--ttl` | duration | stop the sandbox this long after it was created, in use or not, e.g. 2h (0: never) | `0s` |

---
Source: https://docs.kosa8.com/reference/sandbox-create/