Cuttlefish VM

(API Docs)

Cuttlefish is native tooling for AI agents. A coding agent hands off a job — summarize this, classify that, extract these fields — and Cuttlefish runs it locally against a local model, returning a structured result.

Two things make that worth doing:

• Your data stays on your machine. For jobs marked local-only, the calling agent passes paths, not contents. Cuttlefish reads the files itself, so proprietary source and personal data never enter a frontier model's context at all.
• You stop paying frontier prices for grunt work. Bulk, repetitive, and mechanical subtasks don't need a trillion-parameter model. Offloading them keeps tokens and context for the work that does.

The tradeoff is honest and worth stating up front: you cannot run a frontier-class model on a laptop. Cuttlefish is for the large subset of agent work that doesn't need frontier reasoning — not a replacement for it.

How it works

A job is described by a .cuttlefish spec: which model, what it's allowed to touch, and which processing block runs it. The block compiles to WebAssembly and runs sandboxed inside the cuttlefishd daemon, which serves inference from a local model and streams results back.

spec summarize_docs = {
  description = "Use when the agent needs a summary of a local file
                  and content must not leave the machine.";
  model = Ollama "llama3.2:1b";
  data_policy = Local_only;
  capabilities = [ Read "./docs" ];
  block = "../blocks/echo-summarize";
}

Three design decisions shape everything else:

The guest orchestrates; the host does the work. A block is a state machine the daemon drives — it returns commands (Infer, Open, Slice, Done) and the host executes them. Nothing blocks waiting on a callback, so cancellation is simply the host declining to take the next step, and every inference iteration is observable and metered.

Bulk data never enters guest memory. Blocks receive a handle and a length, then pull bounded windows. Guest memory stays flat whether the input is a README or a corpus.

Capabilities are deny-by-default and enforced twice. A block gets no filesystem or network access unless its spec grants it. The grant is checked when the spec compiles and again by the sandbox at runtime — the compile-time check is a convenience, not the security boundary.

Status

Early, but it runs end to end. A .cuttlefish spec drives a sandboxed wasm block through the daemon and returns a structured result, with capabilities enforced and output streamed:

$ cuttlefish run --spec summarize_docs --input '{"path": "examples/docs/a.txt"}'
{
  "result": {
    "path": "examples/docs/a.txt",
    "summary": "The cuttlefish, also known as sepia or sea pen, is a marine animal
                recognized by its ability to rapidly change color and texture to
                blend in with its surroundings."
  },
  "status": "completed",
  "usage": { "duration_ms": 1628, "model": "llama3.2:1b", "tokens_in": 46, "tokens_out": 44 }
}

That is a real local model, not a stub. Multi-block pipelines exist too — a spec's block = "..."; is sugar for a one-node graph; nodes = { name = { block = "..."; in = { field = other_node.out; }; }; ... }; wires up a real DAG with typed fan-in, checked at build time. Still to come: more inference providers, the model pool, the block registry, and the agent harness.

Beyond text

A block is told what it opened, and branches on it:

Open reports pages and has_text_layer for documents, so a block takes the cheap path when it exists and the expensive one when it must — rather than extracting nothing from a scan and summarizing the empty string.

Images never enter guest memory. A block names a handle in its inference request and the host loads the bytes, so a 40 MB scan costs the guest nothing — the same rule that governs file contents.

Rendering PDF pages to images needs the pdf-render feature (pdfium is a large native dependency); text extraction is always available.

Rendering runs in a subprocess. pdfium segfaults on input that pure-Rust parsers accept, and in-process a crash would kill the daemon and every job running alongside it — not just the job holding the bad PDF. Out-of-process it is an ordinary error that one job reports and everything else survives.

Inference providers

A spec names a provider and a target; which backends exist is a property of the build, not of the language:

Adding one means implementing InferBackend and registering a factory — the spec parser, the runner, and the daemon are untouched. Naming a provider this build does not have produces an error listing the ones it does.

Set OLLAMA_HOST to point at a non-default Ollama.

Embedded llama.cpp is opt-in because it compiles llama.cpp from source, which needs cmake, a C++ toolchain, and libclang:

$ nix develop --command cargo build -p cuttlefishd --features llamacpp

It runs the model inside the daemon — no second process, and each job gets its own context so nothing carries between them. Ollama needs none of that toolchain, so prefer it unless you specifically want the model in-process.

Design rationale lives in the code, not in a separate design document — each crate's module docs explain what it is responsible for and why it looks the way it does. Start at the API docs, or read lib.rs of crates/cuttlefish-host for the core of the system. See AGENTS.md for why the project is organized that way.

Development

The toolchain is pinned with Nix, which supplies the exact Rust (host and wasm32-unknown-unknown targets) and Python versions the project expects:

$ nix develop                              # drops you into a shell with everything
$ nix develop --command cargo test --workspace

To run the example job end to end:

$ nix develop --command bash -c '
    cargo build -p cf-block-echo-summarize --target wasm32-unknown-unknown &&
    cargo build -p cuttlefishd -p cuttlefish &&
    ./target/debug/cuttlefishd examples/summarize.cuttlefish \
      --wasm target/wasm32-unknown-unknown/debug/cf_block_echo_summarize.wasm /tmp/cf.sock &
    until [ -S /tmp/cf.sock ]; do sleep 0.1; done
    ./target/debug/cuttlefish run --socket /tmp/cf.sock --spec summarize_docs \
      --input "{\"path\": \"examples/docs/a.txt\"}"
  '

The daemon serves over a unix domain socket on unix and a named pipe on Windows — see Windows below.

Running cargo outside that shell will pick up whatever toolchain happens to be on your PATH, which is a reliable source of confusing errors. If you'd rather not use Nix, check flake.nix for the pinned versions and match them yourself.

Test coverage is measured with cargo-llvm-cov:

$ nix develop --command cargo llvm-cov --workspace          # summary
$ nix develop --command cargo llvm-cov --workspace --html   # browsable report

That is the same command CI runs. There is no coverage service and no upload token — CI publishes the resulting percentage as a small JSON file alongside the API docs, and the badge above renders from it. Coverage data never leaves the build.

Windows

Both binaries run on Windows. The transport is the only thing that ever differed, and it now has a native implementation on each platform:

Pass --endpoint to change it (--socket still works as an alias).

Named pipes rather than a TCP listener on purpose: the daemon's access control is the endpoint's own permissions. It executes wasm and drives local models, so "any process on this machine may connect" would be a materially weaker posture than "whoever can open this endpoint may connect". A loopback port has no such gate and would need an auth token bolted on just to get back to where a socket already is. A named pipe is the Windows analogue, not a workaround.

CI is the authority: Compile and Test (windows-latest) builds both binaries and runs the full suite, including cross-process tests that spawn the real cuttlefish binary.

Building and running Windows binaries from macOS or Linux

Useful for a fast local loop instead of waiting ~8-10 minutes for CI. The x86_64-pc-windows-gnu target is in flake.nix, but the C dependencies in the graph (zstd-sys, ittapi-sys, and two wasmtime build scripts) need a mingw cross-toolchain, which is not in the dev shell — supply it per-invocation:

$ MINGW=$(nix build --no-link --print-out-paths nixpkgs#pkgsCross.mingwW64.stdenv.cc)
$ PTHREADS=$(nix build --no-link --print-out-paths \
    nixpkgs#pkgsCross.mingwW64.windows.mingw_w64_pthreads)
$ nix develop --command bash -c "
    export PATH=\"$MINGW/bin:\$PATH\"
    export CC_x86_64_pc_windows_gnu=x86_64-w64-mingw32-gcc
    export AR_x86_64_pc_windows_gnu=x86_64-w64-mingw32-ar
    export CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=x86_64-w64-mingw32-gcc
    export RUSTFLAGS=\"-L native=$PTHREADS/lib\"
    cargo build -p cuttlefishd -p cuttlefish --target x86_64-pc-windows-gnu
  "

Two traps worth knowing, both of which cost an hour to find:

• Use windows-gnu, not windows-msvc. The msvc target needs the MSVC linker, and its C dependencies fail on a host clang with unsupported option '-fPIC' for target 'x86_64-pc-windows-msvc'. The gnu target builds cleanly with mingw.
• RUSTFLAGS=-L native=…/lib is not optional. Without it the link fails with cannot find -l:libpthread.a: nixpkgs keeps mingw's winpthreads in a package separate from the compiler, so it is not on the search path by default.

The binaries then run under CrossOver or plain Wine:

$ cxbottle --create --bottle cuttlefish --template win10_64   # once
$ export CX_BOTTLE=cuttlefish WINEDEBUG=-all
$ cp target/x86_64-pc-windows-gnu/debug/*.exe \
    ~/Library/Application\ Support/CrossOver/Bottles/cuttlefish/drive_c/
$ wine 'c:\cuttlefishd.exe' 'c:\specs\summarize.cuttlefish' --wasm 'c:\blocks\summarize.wasm' '\\.\pipe\cuttlefish' &
$ wine 'c:\cuttlefish.exe' specs --endpoint '\\.\pipe\cuttlefish'

That works end to end: the daemon binds the pipe, the client connects over it, catalog add/list/show round-trips with byte-identical hashes to a native run, and cuttlefish run completes a real job — file read through the capability check, model called, result returned over the pipe.

Treat Wine as a smoke test, not a gate. It reimplements the Win32 API on unix primitives, so a pass is evidence rather than proof, and a failure may be a Wine gap rather than a real bug. In particular it cannot validate the pipe's access control, which is the property the transport was chosen for — Wine does not meaningfully enforce Windows ACLs. Anything load-bearing still has to go through the Windows CI job, which spawns a real daemon on a real named pipe and runs jobs against it (crates/cuttlefishd/tests/api.rs).

One trap worth knowing when driving a job by hand: a capability grant like Read "./docs" is resolved relative to the spec, but the path in a job's input is resolved against the daemon's working directory. Point them at different places and you get capability_denied on a file that visibly exists inside the granted directory. That is the capability check working, not a bug — a_relative_path_is_resolved_against_the_working_directory_not_the_root in crates/cuttlefish-host/tests/caps.rs pins the rule.

Agent tools

This repo carries its own Claude Code plugin marketplace (.claude-plugin/marketplace.json), so an agent working in a checkout of this repo can install a cuttlefish-catalog skill (exact CLI syntax for cuttlefish catalog add/list/show/rm) and a /cuttlefish-agent-tools:test-catalog command that drives an independent, adversarial exercise of the catalog CLI:

/plugin marketplace add ./
/plugin install cuttlefish-agent-tools@cuttlefish-vm
/reload-plugins

The same thing works from anywhere without a local checkout, using the GitHub shorthand instead of a local path:

/plugin marketplace add cuttlefishvm/cuttlefish-vm
/plugin install cuttlefish-agent-tools@cuttlefish-vm

See plugin/README.md for what the plugin provides.

The skills themselves are plain bash/CLI instructions with no Claude-Code-specific tool references, so they work with any coding agent that can run shell commands and read Markdown — the install commands above are Claude Code's own syntax for adding the marketplace, not the only supported way to use what's inside it.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for how the project is built and tested, and CODE_OF_CONDUCT.md for the standards expected of participants. Security issues should follow SECURITY.md rather than being filed as public issues.

Two conventions worth knowing before you start, both covered in AGENTS.md:

• Documentation lives in the code, as rustdoc. There is no docs/ tree — it is gitignored. Explanations belong next to what they explain, where review catches them going stale.
• Comments explain why, never what. Several of this codebase's choices exist to avoid failures that are invisible from reading the result. Preserve and extend those rather than tidying them away.

Prior art and acknowledgements

Cuttlefish stands on work that came before it:

• rune (hotg-ai) — the "declarative spec compiles to a single portable wasm binary" model, typed dataflow pipelines, and versioned addressable processing blocks all come from rune. Cuttlefish is a successor in that spirit, retargeted from edge ML inference to agent job delegation.
• llama.cpp — local model inference.
• Wasmtime and the Bytecode Alliance — the WebAssembly runtime and the sandboxing model.
• superpowers (obra) — the agent-harness patterns: discovery metadata that states when to use a tool rather than summarizing how it works, and a hard line between what is enforced by code and what is merely suggested in prose.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE_APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE_MIT or http://opensource.org/licenses/MIT)

at your option.

It is recommended to always use cargo crev to verify the trustworthiness of each of your dependencies, including this one.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

The intent of this crate is to be free of soundness bugs. The developers will do their best to avoid them, and welcome help in analysing and fixing them.