# Runtime Instance Model (https://jackin.tailrocks.com/reference/runtime/runtime-instance-model/)
The runtime instance model is the source of truth for how jackin names containers, stores per-instance metadata, decides whether a launch should restore or start fresh, and exposes running instances to `hardline`, `eject`, `purge`, and the console.
## Vocabulary [#vocabulary]
| Term | Meaning |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Role | The reusable tool profile selected by a role key such as `agent-smith` or `chainargos/backend-engineer`. A role repo owns the Dockerfile, manifest, tools, runtime support, and plugins. |
| Instance | One jackin-managed runtime environment created from a role for a workspace or ad-hoc directory. In the Docker backend, the instance is represented by a role container, a DinD sidecar, a network, a cert volume, and jackin-managed state. |
| Agent runtime | One supported CLI runtime: `claude`, `codex`, `amp`, `kimi`, or `opencode`. |
| Agent session | One foreground agent process inside an instance. The initial session is created by `load`; additional sessions are created by `hardline --new`. |
| Durable agent home | The per-instance home/state tree mounted into the role container so agent history, runtime-local config, and auth handoff survive container recreation. |
| Recoverable state | Local jackin-managed state that can rebuild or reconnect an instance after Docker resources disappear. Container writable-layer changes are not recoverable. |
## Core Invariants [#core-invariants]
* Every fresh `jackin load` claims a new DNS-safe instance base name. Running or stopped instances never block a fresh launch.
* Missing recoverable state can block or prompt before a fresh launch because the operator may need to choose between restoring existing work and superseding it.
* `hardline` owns reconnecting, restarting, rebuilding, inspecting, and starting additional sessions inside an existing instance.
* `load` owns creating a fresh runtime instance.
* The per-instance manifest is canonical for identity and lifecycle state; the global instance index is rebuildable lookup acceleration.
* Restore is limited to host-backed state: workspace mounts, isolated worktrees/clones, the per-instance durable agent home, and jackin-managed metadata.
* Docker containers, networks, cert volumes, DinD images, and role-container writable-layer mutations are reconstructible or disposable plumbing.
* Routine operator flows should not require raw Docker names; instance IDs and console rows are the human-facing handles.
## Naming [#naming]
Fresh launches use DNS-safe base names:
```text
jk---
jk--
```
The first form is for saved workspaces. The second form is for ad-hoc launches. The `jk-` prefix identifies all jackin-managed Docker resources. The unique ID comes second so all resources from the same session share a common prefix. Workspace and role components are compact lowercase ASCII alphanumeric strings derived by stripping non-alphanumeric characters (hyphens, slashes, underscores) from the source names. The unique ID makes concurrent launches distinct.
The total base name fits within 58 characters so that `-dind` stays within the 63-character DNS label limit. If the compacted workspace and role components together exceed the available budget they are truncated with a 4-character SHA-256 suffix to keep names deterministic.
Derived Docker resources use the base name:
```text
role container:
dind container: -dind
network: -net
cert volume: -dind-certs
```
DNS-sensitive values such as `DOCKER_HOST`, `JACKIN_DIND_HOSTNAME`, `DOCKER_TLS_SAN`, `NO_PROXY`, `no_proxy`, and `TESTCONTAINERS_HOST_OVERRIDE` use the DNS-safe DinD name. The role-container base must fit the DinD label budget because `-dind` is used as a network hostname.
Implementation lives in crates/jackin-runtime/src/instance/naming.rs and crates/jackin-runtime/src/runtime/naming.rs. The full naming reference — including image names, derived resource names, lock files, roles cache layout, CLI selector formats, and worked examples — is in [Instance and Resource Naming](/reference/runtime/instance-resource-naming/).
## State Layout [#state-layout]
The important instance state lives under jackin' data directory:
```text
data/
├── instances.json
└── /
├── home/
├── state/
├── claude/
├── codex/
├── amp/
├── kimi/
├── opencode/
├── .config/gh/
└── .jackin/
├── instance.json
└── isolation.json
```
`instance.json` stores instance-level identity and lifecycle data: instance ID, container base, workspace name/label, workdir, host workdir fingerprint, role key, role display name, agent runtime, role source/ref, image tag, lifecycle status, last attach outcome, and Docker resource names.
`instances.json` is a global lookup index. It stores enough data to find candidate instances by workspace/directory/role/agent without walking every state directory. If the index is missing, jackin rebuilds it by scanning manifests. The manifest remains canonical.
`isolation.json` is mount-specific. It records materialized isolated mount state such as original source, mount destination, worktree/clone path, worktree scratch branch when applicable, base commit, selector key, container name, and preservation status. It is owned by the isolation subsystem, not the instance manifest.
Implementation lives in crates/jackin-runtime/src/instance/manifest.rs, crates/jackin-runtime/src/isolation/state.rs, and crates/jackin-runtime/src/instance.rs.
## Lifecycle Statuses [#lifecycle-statuses]
The instance manifest uses these lifecycle statuses:
| Status | Meaning |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `active` | Launch started and has not finalized. If the process dies mid-launch, this may become recoverable after Docker reconciliation. |
| `running` | Role container has been observed running. |
| `clean_exited` | Foreground session ended cleanly and no preserved isolated state remains. |
| `crashed` | Role container exited non-zero or was OOM-killed. |
| `preserved_dirty` | An isolated worktree/clone has uncommitted changes after foreground finalization. |
| `preserved_unpushed` | An isolated worktree/clone has commits not pushed or not merged back after foreground finalization. |
| `restore_available` | Docker resources are gone, but local state remains recoverable. |
| `failed_setup` | Launch setup failed before a usable foreground session. |
| `superseded` | Operator chose a fresh launch instead of restoring this instance. |
| `purged` | State was intentionally removed or tombstoned. |
Status writes should update both `instance.json` and `instances.json` through the manifest/index helpers.
## Launch Decision Model [#launch-decision-model]
`jackin load` performs restore discovery before claiming a fresh name. The decision separates Docker-present instances from missing recoverable state:
| Candidate Docker state | Candidate manifest state | Fresh load behavior |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Running role container | Any non-terminal state | Ignore for fresh-load gating; keep discoverable through hardline and console. |
| Stopped role container | Any non-terminal state | Ignore for fresh-load gating; hardline owns restart/reconnect decisions. |
| Docker inspect unavailable | Any relevant state | Surface Docker-specific diagnostics where the current path needs reliable Docker state. |
| Missing container | `active`, `running`, `crashed`, `preserved_dirty`, `preserved_unpushed`, `restore_available`, `failed_setup` | Treat as a restore candidate. Interactive load prompts; non-interactive load fails with guidance when a choice is needed. |
| Missing container | `clean_exited`, `superseded`, `purged` | Ignore. |
Matching role/agent restore candidates can be rebuilt through the load prompt. Related role/agent candidates in the same workspace or directory can be recovered or rebuilt in place from the saved manifest source/ref. Running related instances are not blockers; they are active parallel work.
Implementation lives in crates/jackin-runtime/src/runtime/launch.rs (`resolve_restore_candidate`, related restore helpers, name claiming, and launch orchestration).
## Hardline Decision Model [#hardline-decision-model]
`jackin hardline` targets an existing instance by current directory, role selector, instance ID, or full container base. It inspects the role container and chooses the reconnect path:
| Container state | Hardline behavior |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Running | Attach to the most recently used live foreground session, or start another foreground session when `--new` is supplied. |
| Stopped, exit `0` | Treat as a completed session; use `load` for a fresh instance. |
| Stopped, non-zero or OOM | Restart in place and attach. If DinD is stopped, restart it first. If DinD/network/certs are missing, recreate them around the existing role container before restart. |
| Missing with indexed state | Rebuild the runtime around jackin-managed local state when the workspace or ad-hoc directory can be resolved. |
| Missing without indexed state | Fail with a clear "nothing to reconnect to" path. |
`hardline --inspect` is read-only and should report manifest state even when Docker is unavailable. When Docker can inspect a running role container, it also reports live agent-session inventory from `jackin-capsule status` inside the running container.
`hardline --new` asks the Capsule daemon to create another agent session inside the running container. All agent sessions are equal — there is no "primary" or "secondary" distinction; each lives as a daemon-owned PTY. A subsequent `jackin hardline --new` or console `a` from the same instance attaches to the running Capsule and creates a fresh tab. `hardline --shell` asks the same daemon to create a zsh session without an agent slug.
Implementation lives in crates/jackin-runtime/src/runtime/attach.rs and the hardline dispatch paths in crates/jackin/src/app.rs.
## Console Instance Surface [#console-instance-surface]
The console reads the instance index and shows active/recoverable instances for the selected workspace or current directory. Instance rows expose:
* reconnect/recover (`r`)
* new agent session (`a`/`A`) — asks the Capsule daemon to start an additional agent tab inside the running container
* shell session (`x`/`X`) — asks the Capsule daemon to start a zsh tab without an agent slug
* read-only inspect (`i`)
* guarded purge (`p`)
The console should treat the index as a discoverability source, not as proof that Docker resources still exist. Refresh paths reconcile local state with Docker when an action needs live container data.
Implementation lives in crates/jackin/src/console/tui.rs, crates/jackin-console/src/tui/screens/workspaces/view/list.rs, and crates/jackin-console/src/tui/input/list.rs.
## Persistence Boundary [#persistence-boundary]
Persisted:
* agent conversation history and runtime-local settings under the per-instance durable home
* agent auth handoff state for supported runtimes, according to the resolved auth mode
* GitHub CLI state stored for the instance
* isolated worktree/clone state and metadata
* instance manifest, index entry, and last attach outcome
Not persisted:
* packages installed interactively into the role container filesystem
* files written only to the role container writable layer outside mounted paths
* DinD images, containers, volumes, and build cache
* Docker networks and TLS cert volumes after Docker-side deletion
This boundary is deliberate. Durable tools belong in the role Dockerfile. Durable work belongs in mounted paths or jackin-managed per-instance state.
## Cleanup And Purge [#cleanup-and-purge]
`eject` stops/removes Docker resources for an instance while preserving local recovery state unless purge is requested. `purge` deletes local recovery state and is guarded when matching Docker resources still exist. `exile` stops all running managed role containers.
Plain purge must refuse while the role container or DinD sidecar still exists, whether running or stopped. This prevents deleting local state that an existing Docker resource may still depend on. `eject --purge` is the combined path when the operator wants Docker resources and local recovery state removed together.
Implementation lives in crates/jackin-runtime/src/runtime/cleanup.rs.
## Source References [#source-references]
| Area | Source |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DNS-safe names and instance IDs | crates/jackin-runtime/src/instance/naming.rs |
| Docker labels and derived resource names | crates/jackin-runtime/src/runtime/naming.rs |
| Instance manifest and rebuildable index | crates/jackin-runtime/src/instance/manifest.rs |
| Launch, restore discovery, name claiming | crates/jackin-runtime/src/runtime/launch.rs |
| Attach, inspect, session inventory | crates/jackin-runtime/src/runtime/attach.rs |
| Eject, purge, orphan cleanup | crates/jackin-runtime/src/runtime/cleanup.rs |
| Workspace/materialized mount state | crates/jackin-runtime/src/isolation/materialize.rs and crates/jackin-runtime/src/isolation/state.rs |
| Foreground finalizer | crates/jackin-runtime/src/isolation/finalize.rs |
| Console instance rendering/actions | crates/jackin-console/src/tui/screens/workspaces/view/list.rs and crates/jackin-console/src/tui/input/list.rs |
| DinD/Testcontainers smoke coverage | crates/jackin/tests/dind\_e2e.rs |