orca/docs/namespace.md

Namespace and Paths

Orca stores all on-disk state under a single namespace root directory. The v0.9 re-architecture introduced a multi-namespace layout (R-002) where each namespace is a self-contained directory tree with its own database, jobs, allocs, env, and secrets. A cluster/ directory holds cluster-wide artifacts shared across namespaces.

v0.9 layout (canonical): This document describes the v0.9 multi-namespace layout. The v0.8 flat layout (orca.db, ca.crt, server.crt at the root) is deprecated and will be removed in v0.11. See v0.8 flat layout below.

Namespace root resolution

The namespace root is resolved in this order:

1. If --system flag is passed → root is /root/.orca (errors if ORCA_HOME is set to a conflicting value).
2. Else if ORCA_HOME is set → root is $ORCA_HOME.
3. Else → root is ~/.orca ($HOME/.orca).

ORCA_HOME (REQ-041)

Set the ORCA_HOME environment variable to change the namespace root for all orca components:

export ORCA_HOME=/var/lib/orca
orca init          # creates /var/lib/orca/
orca ns create prod

--system (REQ-042)

The --system persistent flag selects the system-level namespace root /root/.orca:

sudo orca --system init          # creates /root/.orca/
sudo orca --system ns list

If ORCA_HOME is already set to a different value, --system returns an error (to avoid silent namespace mismatches).

v0.9 multi-namespace layout (R-002)

$ORCA_HOME/
├── cluster/                  # cluster-wide (NOT a workload namespace)
│   ├── ca.crt, ca.key        # step-ca root (R-006, D-101)
│   ├── master.key            # AES-256-GCM root (R-011, mode 0600)
│   ├── config.md             # Markdown frontmatter config (R-014)
│   ├── known_hosts           # SSH known_hosts (D-035)
│   ├── orca_ssh_key          # orca SSH private key (D-037)
│   ├── orca_ssh_key.pub      # orca SSH public key
│   ├── peers/<host>/         # per-peer directory
│   ├── txns/                 # cluster transaction log (R-016)
│   └── state/                # cluster state
├── _defaults/                # implicit root namespace (always exists)
│   ├── ns.md                 # namespace frontmatter (kind: Namespace)
│   ├── .env                  # per-namespace env
│   ├── .env.secrets          # encrypted secrets
│   ├── db/orca.db            # per-namespace SQLite database
│   ├── jobs/                 # submitted jobspecs
│   └── alloc/                # allocation state
├── <explicit-namespace>/     # operator-created (e.g., prod, staging)
│   ├── ns.md
│   ├── .env, .env.secrets
│   ├── db/orca.db
│   ├── jobs/, alloc/
│   └── syncthing/            # Syncthing config (if replicated volumes)
└── orca_cache.db             # CLI-side cache (R-008)

Key points

• _defaults/ is the implicit root namespace (D-159). It always exists. Every namespace inherits from _defaults and cannot opt out (D-185, D-187).
• cluster/ is NOT a workload namespace — it holds cluster-wide artifacts (CA, master key, SSH keys, known_hosts, peers, txns).
• Per-namespace DBs: each namespace has its own db/orca.db (R-002). No namespace column in SQLite.
• Namespace inheritance: child namespaces inherit env and constraints from parents (via ns.md frontmatter parents: field). _defaults is always appended last in the inheritance chain.
• orca ns subcommands: list, create, delete, inspect, validate — see docs/cli.md.

Path reference (internal/paths/)

Function	Path	Contents
Root()	$ORCA_HOME	Namespace root
ClusterDir()	Root()/cluster	Cluster-wide artifacts
NamespaceDir(ns)	Root()/ns	Per-namespace directory
NSDb(ns)	Root()/ns/db/orca.db	Per-namespace SQLite DB
NSEnv(ns)	Root()/ns/.env	Per-namespace env
NSSecrets(ns)	Root()/ns/.env.secrets	Encrypted secrets
NSJobs(ns)	Root()/ns/jobs	Jobs dir
NSAlloc(ns)	Root()/ns/alloc	Alloc dir
NSMd(ns)	Root()/ns/ns.md	Namespace frontmatter
DefaultNamespace()	_defaults	Implicit root (D-159)
CACertPath()	ClusterDir()/ca.crt	step-ca root (D-101)
MasterKeyPath()	ClusterDir()/master.key	AES-256-GCM root key
KnownHostsPath()	ClusterDir()/known_hosts	SSH known_hosts
SSHKeyPath()	ClusterDir()/orca_ssh_key	orca SSH private key
ConfigPath()	ClusterDir()/config.md	Markdown config (R-014)
CacheDB()	Root()/orca_cache.db	CLI-side cache (R-008)
PeersDir()	ClusterDir()/peers	Peers directory
TxnDir()	ClusterDir()/txns	Transaction log (R-016)

Creating and managing namespaces

# List all namespaces
orca ns list

# Create a namespace (inherits from _defaults)
orca ns create prod

# Create a namespace with an explicit parent
orca ns create staging --parent prod

# Inspect the effective inheritance chain + merged env
orca ns inspect prod

# Validate a namespace's inheritance chain
orca ns validate prod

# Delete an empty namespace (refuses if jobs/ or alloc/ non-empty)
orca ns delete staging

See docs/cli.md for the full orca ns reference.

ORCA_DB override

For finer-grained control, ORCA_DB overrides only the database path (not the cert/namespace paths). This is primarily a testing affordance.

export ORCA_DB=/tmp/test.db
orca init   # uses /tmp/test.db for the DB, ~/.orca/ for everything else

Deprecated: v0.8 flat layout

Deprecated in v0.9: The v0.8 flat layout (orca.db, ca.crt, ca.key, server.crt, server.key at the namespace root) is superseded by the v0.9 multi-namespace layout (R-002). The v0.8 layout is supported during the dual-write window via internal/certpaths (a thin shim) and will be removed in v0.11.

The v0.8 flat layout stored all state at the namespace root:

Path	Contents
~/.orca/orca.db	SQLite database
~/.orca/ca.crt	CA certificate
~/.orca/ca.key	CA private key
~/.orca/server.crt	Server certificate
~/.orca/server.key	Server private key

The v0.9 re-architecture moved these to cluster/ (CA, SSH keys) and per-namespace db/ (SQLite) to support multi-tenancy (R-002). The orca doctor --legacy-paths command (v0.11-P14c) will detect v0.8 residue and recommend migration.

See also

• Install Guide — 1-liner install with install.sh.
• Docker Guide — running orca in a container.
• CLI Reference — orca ns subcommands.
• Jobspec Reference — markdown frontmatter schema.