Commands for the core box lifecycle. For the concepts behind boxes, refs, and publishing, see Boxes.

​
create

Create a box from a base image or by cloning another box 
4kr create <NAME> [options]
Argument / optionDescription
<NAME>Name.
-b, --base <BASE>Base image to create from [default: box-base]
-f, --fork <FORK>Create by cloning another box filesystem (cannot combine with —base)
-t, --tag <TAGS>Tag as key=value (repeatable); used for filtering with 4kr list -t
-d, --data <DATA>Attach a persistent data volume as NAME=/mount/path[:ro|:rw] (repeatable)
-e, --env <ENV>Environment variable as KEY=VALUE (repeatable)
--cpu <CPU>CPU cores (e.g. “2” or “500m”)
--memory <MEMORY>Memory limit (e.g. “2G”, “512M”)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Create a box with the default base
4kr create my-box

# Create from a specific base image
4kr create my-box --base ubuntu-base

# Create from a tagged base build (alias:script_sha256)
4kr create my-box --base box-base-postgres-17:0123abcd...

# Clone an existing box (copies its entire filesystem)
4kr create my-box --fork my-box

# Attach a persistent data volume at a mount path
4kr create my-box --data mydata=/data

# Attach multiple data volumes
4kr create my-box --data pg=/var/lib/postgresql --data cache=/cache

# Create with resource limits and tags
4kr create my-box --cpu 2 --memory 4G -t env=staging

# Clone a box in a specific project
4kr create new-box --fork old-box -p my-project

​
list

List boxes in a project 
4kr list [options]
Argument / optionDescription
-a, --allList boxes across all projects
-q, --quietPrint only box names (useful for scripting)
-t, --tag <TAGS>Filter by tag as key=value (repeatable, AND logic)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# List boxes in current project
4kr list

# List across all projects
4kr list --all

# Filter by tags (multiple tags = AND filter)
4kr list -t env=staging -t region=us

# Names only (useful for scripting)
4kr list --quiet

​
show

Show box details 
4kr show <FORK> [options]
Argument / optionDescription
<FORK>Box ref.
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
-f, --forceForce the operation.
# Show box details
4kr show my-box

# JSON output
4kr show my-box --json

# Show box in another project
4kr show myproject:my-box

​
update

Update a box’s environment variables, resources, or tags 
4kr update <FORK> [<SETTINGS>...] [options]
Argument / optionDescription
<FORK>Box ref.
<SETTINGS>Settings as KEY=VALUE (env vars, or PORT/CPU/MEMORY for resources) (repeatable)
--env <ENV>Environment variable as KEY=VALUE (repeatable)
-t, --tag <TAGS>Update tags as key=value (repeatable, replaces existing tags)
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Set environment variables
4kr update my-box NODE_ENV=production DEBUG=true

# Update exposed port for ingress
4kr update my-box PORT=8080

# Change resource limits
4kr update my-box CPU=2 MEMORY=4G

# Update tags
4kr update my-box -t version=2.0 -t status=active

# Combine settings and tags
4kr update my-box PORT=3000 -t env=prod

​
publish

Publish a box at a public hostname 
4kr publish <FORK> [<SUBDOMAIN>] [options]
Argument / optionDescription
<FORK>Box ref.
<SUBDOMAIN>Subdomain to publish at (.); use @ for apex domain
--host <HOST>Publish at an explicit hostname
--domain <DOMAIN>Override default publish domain
-f, --forceForce takeover if subdomain is already published elsewhere
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Publish box at a subdomain (uses default domain)
4kr publish my-box myapp
# => https://myapp.<default-domain>

# Publish at an explicit hostname
4kr publish my-box --host chat.example.com

# Publish with custom domain
4kr publish my-box myapp --domain example.com

# Publish at apex of the target domain
4kr publish my-box @ --domain example.com

# Force takeover from another box
4kr publish my-box myapp --force

​
unpublish

Remove a box publish 
4kr unpublish <FORK> [<SUBDOMAIN>] [options]
Argument / optionDescription
<FORK>Box ref.
<SUBDOMAIN>Subdomain to unpublish; use @ for apex domain
--host <HOST>Unpublish an explicit hostname
--domain <DOMAIN>Override default publish domain
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Remove a published subdomain
4kr unpublish my-box myapp

# Remove an explicit hostname publish
4kr unpublish my-box --host chat.example.com

# Remove apex publish
4kr unpublish my-box @ --domain example.com

# With custom domain
4kr unpublish my-box myapp --domain example.com

​
delete

Delete one or more boxes 
4kr delete <BOXES>... [options]
Argument / optionDescription
<BOXES>Box names to delete (repeatable)
-f, --forceForce delete without confirmation
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
# Delete a box
4kr delete my-box

# Delete multiple boxes
4kr delete box-1 box-2 box-3

# Force delete without confirmation
4kr delete my-box --force

​
stop

Stop a running box; its filesystem is preserved 
4kr stop <FORK> [options]
Argument / optionDescription
<FORK>Box ref.
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
-f, --forceForce the operation.
# Stop a running box (filesystem is preserved)
4kr stop my-box

# Resume later with: 4kr resume my-box

​
resume

Resume a stopped box 
4kr resume <FORK> [options]
Argument / optionDescription
<FORK>Box ref.
-p, --project <PROJECT>Target project.
-j, --jsonPrint the JSON response.
-f, --forceForce the operation.
# Resume a stopped box
4kr resume my-box

​
inject

Copy local credentials (SSH key, Codex auth, gitconfig) into a box 
4kr inject <FORK> [options]
Argument / optionDescription
<FORK>Box ref.
--codex-auth <CODEX_AUTH>Path to Codex auth.json (default: ~/.codex/auth.json)
--codex-toml <CODEX_TOML>Path to codex.toml (default: ~/.codex/config.toml)
--ssh-key <SSH_KEY>Path to SSH private key (default: ~/.ssh/id_ed25519, id_rsa, id_ecdsa)
-p, --project <PROJECT>Target project.
# Inject with auto-discovery of credentials
4kr inject my-box

# Specify custom paths
4kr inject my-box --ssh-key ~/.ssh/id_ecdsa --codex-toml ./custom.toml