Deckent

Agent Control & Execution Plane

Deckent combines a customer-installed runtime, a budget ceiling before every paid API call, sandboxed tools and MCP, governed approvals, and one typed application contract for human and AI entry points.

policy-driven agent runtime · governed execution · self-hosted agent control plane

Türkçe · What it is · How a request flows · First session · In the terminal · Safety · Get started

Note

Pre-release 1.0.0-alpha.23 (released 2026-10-09). Deckent is not on npm yet; install it from source as shown in Get started. Every release is listed in CHANGELOG.md.

What is Deckent

Deckent runs on your own machines and brings policy, approvals, execution and durable records together. Before a paid API call it reserves the maximum charge against the scope's budget; an unknown price or insufficient budget refuses the call. People use the terminal or deckent command; AI agents and integrations use MCP or the SDK. These entry points share one typed application contract.

MCP uses a separate actor with observation-only default grants; changing budgets, activating models or invoking them requires an explicit policy grant naming that MCP actor. Human approval decisions require interactive terminal input and output.

The open-source Core (Apache-2.0) works on its own. The planned proprietary Enterprise edition is designed to layer on through the registry without editing Core, as a separate distribution. Today the public extension entry lets a CLI distribution register effect adapters and secret-store adapters. Since alpha.20, that distribution can also start the service and MCP entry with its registrations; automatic service start and restart replay the distribution's entry. Core's bare executables do not discover those modules. Enterprise SSO, ERP integrations and fleet management remain planned capabilities.

🗼 Govern	One identity, scope and policy model for people and AI agents. When something needs approval, the window shows exactly what: the full command, where it runs, on whose behalf, the risk, whether it can be undone, and a deadline. A persona or a model's advice never grants authority.
🛫 Execute	Runs, tasks and workers are admitted, scheduled and recovered on your machines. Agent shell commands and MCP servers run in sandboxes (bubblewrap, Landlock); workers run in Docker. Works with Anthropic, OpenAI, DeepSeek, Z.ai (GLM), a local server or an OpenAI-compatible endpoint with published pricing, and OpenRouter model connections (paid calls require verified pricing and routing), and with Claude Code, Codex and Cursor workers.
📜 Prove	Every decision and effect lands in a durable ledger and audit trail. Approvals are sealed, patches are retained, and changes are integrated in an isolated candidate before anything is delivered.

How a request flows

You ask for something in plain words. Deckent turns it into checked, isolated steps, and nothing runs unless policy and your permission mode allow it.

sequenceDiagram
  autonumber
  actor You
  participant T as Deckent terminal
  participant R as Runtime service
  participant P as Policy and approvals
  participant B as Sandbox
  participant L as Ledger
  You->>T: "Run the tests and fix the failing one"
  T->>R: agent turn (model + tools)
  R->>P: may this tool call run here, for this person?
  alt needs approval
    P-->>You: approval window (what, where, who, risk, deadline)
    You->>P: yes once · no · note
  end
  P-->>R: allowed
  R->>B: run the command in the sandbox
  B-->>R: output + write set
  R->>L: record the call, decision and effect
  R-->>T: streamed answer
  T-->>You: result, with every step visible

Loading

Your first session

From an empty project to a governed agent turn and what it cost, without leaving Deckent:

flowchart LR
  I["1 · Set up<br/><sub>deckent init policy</sub>"] --> O["2 · Open<br/><sub>deckent</sub>"]
  O --> P["3 · Connect a provider<br/><sub>/provider · key · free check</sub>"]
  P --> B["4 · Set a budget<br/><sub>Create budget · USD</sub>"]
  B --> M["5 · Choose a model<br/><sub>/model · session or default</sub>"]
  M --> W["6 · Work<br/><sub>approvals · modes</sub>"]
  W --> U["7 · Check usage<br/><sub>/usage · spend account</sub>"]

Loading

A scope is the stable identifier used to bind policy, work records and spending to this project. --scope my-project selects that identifier, not a directory or a sandbox. For a new project, choose it when previewing the initial policy; for an existing installation, use its configured scope ID. Reuse the same ID for subsequent commands. The terminal defaults to terminal.scopeId; open it with deckent --scope my-project to select this scope explicitly. See the glossary for scope and realm definitions.

deckent init policy --scope my-project --preview
deckent init policy --scope my-project --apply

1. Set up once per project: deckent init policy --scope <id> --preview shows the first-run policy and deckent init policy --scope <id> --apply installs it, writes the default terminal scope and chat limits, and initializes cancellation settings and an empty migrated ledger. Choose a scope name such as my-project. It lets you connect and call models, keep keys and set budgets in that scope; every one of those actions is still checked and recorded. On Linux, WSL and macOS a fresh installation starts on the encrypted key store.
2. Open the terminal with deckent (or deckent --scope my-project for an explicit scope).
3. Connect a provider with /provider: Anthropic API, OpenAI API, DeepSeek API, Z.ai GLM, a local server such as vLLM, or an OpenAI-compatible endpoint with published pricing. You type the key into a masked field; Deckent checks it with a free request and stores it in the secret store under its name; a key the check rejects is never stored. Where a provider has no free check, the key is kept unverified and the first turn shows any rejection. The value is never shown again and no agent or worker ever receives it. Then choose Connect a model. Providers with a packaged catalog offer those models; for a provider without one, choose an address, then select an exact ID from its bounded /v1/models list. Deckent stores that ID unchanged. Local loopback models are free-measured; a remote model without a verified published price is listed but locked, with the reason and the next step (Zhipu GLM China stays locked because its prices are in CNY). OpenRouter offers model connections; paid calls still require verified pricing and routing. The same from the command line: deckent secret set <NAME> and deckent models connect --scope <id> --connection <kind> --command-id <id> --model <exact id>.
4. Set a budget. Every model turn reserves against one shared USD budget of the scope; without one, every turn is refused and the windows say so. The first row of /provider, Create budget, opens the budget window: 5, 10, 25, 50 or 100 USD, or another whole-dollar amount from 1 to 1000 with the arrow keys, then a confirm step. Later the same row reads Change budget. From the command line: deckent models create-budget --scope <id> --usd <n> and deckent models revise-budget --scope <id> --usd <n>.
5. Choose a model with /model. It lists the catalog's models; one you cannot use yet is locked with the reason (no budget, not connected, key missing, not activated) and what fixes it. Pick This session only or This session, and make it my default (your terminal.defaultModel). When the project names its own model, the window says which setting chose the model in use.
6. Work. Ask in plain words. Tool calls follow your company policy and your permission mode; anything that needs you opens the approval window (see Safety model).
7. Check usage with /usage: the tokens this conversation measured (reasoning shows not measured when the provider did not report it) and the scope's budgets; open a budget to read its spend account: limit, reserved and settled.

Before a budget. /model locks every model and names the reason and the next step.	/provider. Create budget first, then each provider with its connection state.
Budget window. Preset amounts, or another amount with the arrow keys.	Another amount. Whole dollars, 1 to 1000; nothing is typed and nothing is sent before you confirm.
After the budget. The connected model is ready; the other stays locked until it is connected. The framed line above records the budget.	/usage. Tokens this conversation measured and the scope's budgets. A measurement, not an invoice.

In the terminal

These screens come from the real Deckent terminal (alpha.17, 120×36), recorded in a throwaway sample project. The model is a small test server on the same machine: no provider was called and no real key was used.

Every slash command answers in its own window. Esc closes it and leaves one framed Deckent system line in the conversation instead of a wall of text. Settings are changed by choosing, not by typing: /config walks from section to key to the allowed values, numbers move with a bounded arrow-key stepper, and only a few fields (such as an allowed fetch host or a registry address) take typed text, which is checked first. Each change goes through policy and may become an approval.

Chat. Your lines and Deckent's answers are visibly distinct, with time and tokens per turn.	Approval window. What, where (sandbox), on whose behalf, scope, why, risk, reversibility and a live deadline. y once · n decline · Tab note.
/status. A human summary first; identities, process and build under the details.	Modes. Shift+Tab cycles the modes you are allowed; full access is clearly marked.
/help. Commands grouped by purpose, one line each.	/mcp. Add a server step by step; configured servers with their trust state.
/provider. Each provider's state. OpenRouter now offers model connections; this screenshot predates them.	/config. Section, key, then one of the allowed values; the current one is marked.
System lines. Each closed window leaves one framed summary line.	/tasks. Workers and runs in one live, read-only window (empty here: no background work yet).

Safety model

External MCP clients start with observation-only permissions. Open /policy (MCP permissions), choose an existing scope and a capability group, then grant or revoke it after reviewing the exact rules. Applying requires an attested terminal approval and is audited; no policy JSON needs typing. Pool control, catalog registration and global model configuration are marked all scopes. Revoking a group preserves other grants, which may still allow a tool. “Dogfood worker” is a proposed work-only preset; its exact N1 MCP usage is unverified.

CLI choices come from deckent policy mcp list --json:

deckent policy mcp grant --group work --scope <existing-scope> --preview
deckent policy mcp grant --group work --scope <existing-scope> \
  --apply --expect <preview-digest>
# Revoke: the same two steps with `revoke` instead of `grant`.

Every tool call an agent makes is decided by two things together: your organization's policy and the permission mode you chose. You move between the modes you are allowed with Shift+Tab, or with /mode.

flowchart LR
  S["Standard<br/><sub>edits run · shell and MCP ask</sub>"] -->|Shift+Tab| C["Careful<br/><sub>edits ask too</sub>"]
  C -->|Shift+Tab| A["Full auto<br/><sub>sandboxed shell and MCP run</sub>"]
  A -->|Shift+Tab| F["Full access<br/><sub>company grant · this session · every call audited</sub>"]
  F -->|Shift+Tab| S
  H[["Hard floor · enforced in every sandbox mode<br/>Deckent configuration, policy, approvals, secrets, MCP registry"]]

Loading

Mode	Runs without asking	Asks first
Standard	Reads, ordinary file edits	Shell commands, protected paths, MCP calls
Careful	Reads	Every edit as well
Full auto	Edits, sandbox-contained shell commands, MCP calls	Destructive commands (rm -r, …), protected paths
Full access	Everything company policy allows above the hard floor; every effect call is audited	The hard floor and whatever company policy still requires (a deny always wins); needs a company grant and lasts for the session

In standard, careful and full auto, sandboxed shell commands get a closed view: the project is writable within the call's approval rules, .git is read-only, HOME is hidden and network access is off. Approved commands still cannot write Deckent authority files. Landlock also refuses permission and ownership changes, and cannot add or remove entries in directories holding protected paths. Full access requires a usable open bubblewrap sandbox: network and HOME are available, while Deckent state, configuration, credential patterns and host Docker/session D-Bus sockets remain masked or read-only. Without an open sandbox, full-access shell calls are refused, including an explicit host realm. Closed modes retain the visible prefer-sandbox host fallback; that fallback has no enforced filesystem boundary, so use require-sandbox when confinement is required. The shared credential registry covers gh, Docker, kube, Codex, Git credentials and common cloud CLIs. HOME masking is bounded (depth 3, 20,000 entries); custom locations, arbitrary filenames and aliases outside those masks need separate isolation. Full auto still asks before find -delete, file truncation (>, >|) and moves (mv); appends (>>) remain modifications.

API keys

You store a provider key once, in the masked field of /provider or with deckent secret set NAME (hidden prompt or piped stdin, never an argument); a model profile refers to it by name. Never put it in ANTHROPIC_API_KEY, a shell profile or a .env file: other tools read those.

Store (secrets.store)	On disk	Who can read the key
core.secret-store.env@1 (when no store is selected)	nothing; read from the environment	every program that inherits that environment
core.secret-store.file@1	plain text, a 0600 file	Deckent and other programs running as your user
core.secret-store.encrypted-file@1 (recommended; fresh installs start here)	encrypted (AES-256-GCM); the unlock key sits in the same folder, no passphrase	Deckent; other programs running as your user can still open it

Provider calls resolve keys inside the runtime; keys are not placed in prompts or the shell environment. Supported sandbox views hide the store; a host realm or fallback has no filesystem confinement. A provider answer that echoes a stored key is refused. deckent doctor shows which store is active and who can read it. When a provider refuses a key (401/403) or a limit is reached, the terminal says so in plain words; spend limits stay in your provider account.

Strict install, for keys no other program on the machine should read:

Fresh Linux/WSL/macOS installations select the encrypted store through init policy --apply and Docker init apply when the installed policy permits the switch; existing installations keep their selection.

1. Move your keys into the encrypted store: deckent secret store lists the registered stores to pick from; leaving env lists config reference names missing in the target and asks yes/no (scripts require --confirm-env-missing); doctor shows the same names; it copies every key, checks it, selects the new store and then removes the old copy (a move to a weaker store asks first). Installations set up with deckent init policy on Linux, WSL and macOS start on the encrypted store already.
2. Keep other AI tools out of Deckent's state folder, e.g. Read deny rules for the store files in Claude Code's ~/.claude/settings.json. This stops their file tools and common shell commands, not every script.
3. Planned: run the Deckent service under its own OS user (or the macOS Keychain) so no program of your account can read the keys.

The file stores are not available on native Windows yet.

Spending

Each scope has one shared budget in USD for every API provider. Before a paid call, Deckent reserves the most it could cost at the dearest price tier that can apply; afterwards it settles the call from the usage the provider itself reported in its final answer, multiplied by the verified published price. That settled amount is Deckent's own calculation, not the provider's invoice. A remote model without a verified price is refused and shown locked with the reason. Where a provider does not say which price tier it used (DeepSeek), the call settles at the published peak price and is labelled an upper bound. A call that never received its final usage stays held until you resolve it with deckent models reconcile-spending. If a settled charge ever exceeds what was reserved, the scope stops admitting new calls until you lift the freeze with deckent models revise-budget --scope <id> --usd <n> --unfreeze.

Architecture

Every way in speaks the same typed contract. Runtime-backed operations go through one runtime service, which checks identity, scope and policy on each operation, writes the result to the ledger and lets effects happen only inside the place the policy allows. Installation, observation and some patch operations use the same contract locally, without the service.

flowchart LR
  subgraph Ways in
    T[Terminal]
    C["deckent command"]
    M[MCP server]
    S[SDK]
  end
  T & C & M & S --> R["Runtime service<br/>one typed contract"]
  R --> P["Policy · approvals<br/>identity · scope"]
  R --> L[("Ledger · audit")]
  R --> X["Runs · tasks · workers"]
  X --> B["Sandboxes<br/>bubblewrap · Landlock · Docker"]
  R --> G["Model providers<br/>Anthropic · OpenAI-compatible · vLLM"]
  R --> N["MCP servers<br/>sandboxed · trust-pinned"]

Loading

What you can do today

• Work with an agent in the terminal: streamed turns, file edits and a sandboxed shell, approval and monitor windows, permission modes, MCP tools, conversation compaction, English and Turkish.
• Orchestrate work: admit Runs, Tasks and Attempts, schedule dependencies, reserve capacity, cancel and recover, all recorded in a durable SQLite ledger.
• Use coding workers: Git-backed checkouts and Docker workers with Claude Code, Codex and Cursor; patches are retained, integrated in an isolated candidate, then delivered or released.
• Govern: local identity, company-scoped policy, audit and one approval broker for every surface; human acceptance or rejection of unverified evidence.
• Choose models: a model catalog by client and billing channel, exact activation, local vLLM chat; /provider and /model connect a provider with your own key and pin a model for the session or make it your default; paid calls settle from the provider's usage times a verified published tariff under a budget you set in the budget window or with deckent models create-budget (an unpriced remote model is refused and locked with the reason); spending and allocation audit.
• Cache prompts and watch the cost: new Anthropic profiles use the 5-minute prompt cache and existing ones change only by your choice; /usage shows the live account in USD, cache reads and writes, and the estimated net benefit.
• Use OpenRouter models in the terminal: connect your key in /provider; tools and streaming work, and the cost OpenRouter reports settles each call under your budget. Before the first paid OpenRouter call, check https://openrouter.ai/settings/plugins that no plugin is enabled with "Prevent overrides", and set an OpenRouter credit limit no higher than your Deckent budget; Deckent cannot see either setting.
• Back up and restore: deckent backup create|verify|restore writes encrypted, verifiable recovery sets, on a schedule if you choose, with retention; a restore runs only while the service is stopped.
• Operate: deckent monitor for a read-only view of every installation, deckent doctor for health, deckent config for settings, bilingual help everywhere.

Not yet available: autonomous business-process coordination (Mission/do), Enterprise SSO and fleet management, a remote HTTP API, Desktop and Dashboard. A Docker worker shares the host kernel and is not a virtual machine.

Roadmap

flowchart LR
  L["Released · alpha.23<br/>terminal windows · approval window · slash-command windows<br/>/config · /mode · /mcp · /provider · /model<br/>easy MCP (HTTP, import, trust) · encrypted key store<br/>spend settlement and budgets · OpenRouter models · prompt cache"] --> P["In progress<br/>cost guards · per-provider spend limits<br/>cache breakpoints and compaction triggers"]
  P --> N["Next<br/>subscriptions · worker credential modes<br/>system prompt and settings<br/>project instruction file"]
  N --> F["Planned<br/>Firecracker microVM sandbox<br/>HTTP API · Dashboard · Desktop"]

Loading

Get started

Deckent runs on Linux or Windows through WSL2 with Node.js ≥ 24.15.0 (Node 24 and 26 are supported). Native Windows runtime transport is not supported. A fresh source build needs Docker to build and stage the locked bubblewrap (currently 0.13.0); it downloads and verifies the locked source and binary digests. A verified staged bundle can be reused offline. System bubblewrap, when selected, must be ≥ 0.12.0. Docker is also required for coding workers; the first terminal session itself does not need Docker or a paid call. A C build toolchain is also required for the native sandbox helper. Until npm publication, build once:

git clone https://github.com/Verhex/deckent-next.git
cd deckent-next
npm ci
node scripts/build-bwrap.mjs --arch all --out .pack/bwrap/first-build
node scripts/build-bwrap.mjs --stage-dev .pack/bwrap/first-build
npm run build
npm link

Use a fresh --out directory for another build. Do not proceed with sandbox work if the build reports bubblewrap=ABSENT; inspect the sandbox posture with deckent doctor. See the contributor quickstart for prerequisites and one test without a provider key.

After linking, change to your own project folder, outside the Deckent source checkout. Long paths and spaces work: the local socket uses a short private directory per installation. npm run build fails clearly if it cannot stage the locked bubblewrap; start Docker and retry, or use DECKENT_BWRAP_BUILD=<verified build-bwrap output> npm run build.

From then on, everything is deckent:

deckent --version
deckent init policy --scope my-project --preview
deckent init policy --scope my-project --apply
deckent doctor                            # non-zero if setup cannot start
deckent                                   # opens in the scope selected by init
# deckent --scope my-project               # explicit scope, same terminal
deckent init preview --profile <file>     # preview the installation for a project
deckent mcp add context7 -- npx -y @upstash/context7-mcp   # add an MCP server
deckent monitor                           # watch installations and work
deckent --help                            # every command; deckent <command> --help for details

Learn more

• Architecture overview: layers, security, extension points and current limits
• Glossary: scope, realm, work lifecycle, approvals and spending
• ARCHITECTURE.md: detailed engineering contracts and implementation notes (English/Turkish)
• Operator reference: worker toolchains, worker images, coding profiles, patch custody and installation custody rules
• CHANGELOG.md: what each release brought
• CONTRIBUTING.md · Code of Conduct · Security

License

Apache-2.0 (see LICENSE).