Install

maiden is a single binary with no runtime dependencies. Pick whichever channel fits how you already install things.

Script

curl -fsSL https://maiden.sh/install.sh | sh

It detects your platform, downloads the matching release archive, and installs to /usr/local/bin — or ~/.local/bin if that isn’t writable, in which case it tells you to put that on your PATH.

Pin a version with sh -s -- --version v0.1.0. The same script is served straight from the repository, if you would rather not go through the domain:

curl -fsSL https://raw.githubusercontent.com/jondot/maiden/main/install.sh | sh

Cargo

cargo install maiden

Builds from source, so it works on any target Rust supports — including ones with no prebuilt archive.

npm

npm install -g @jondot/maiden

The main package is a launcher; the actual binary comes from a platform package resolved through optionalDependencies. Useful when your toolchain is already Node.

Docker

docker run --rm ghcr.io/jondot/maiden:latest --help

To run your own agent, mount it and expose the port:

docker run --rm -p 8080:8080 \
  -v "$PWD/my-agent:/agent" \
  -e OPENAI_API_KEY \
  ghcr.io/jondot/maiden:latest serve /agent --port 8080

The image sets MAIDEN_BIND=0.0.0.0, since the default 127.0.0.1 is unreachable from outside a container.

Verify a download

Release archives are signed with cosign keylessly, through GitHub’s OIDC provider. There is no static public key to trust — the signature is bound to the workflow run that produced the artifact.

cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/jondot/maiden/\.github/workflows/release\.yml' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate maiden-aarch64-apple-darwin.tar.gz.crt \
  --signature maiden-aarch64-apple-darwin.tar.gz.sig \
  maiden-aarch64-apple-darwin.tar.gz

Platform support

Platform	Prebuilt archive	Notes
macOS arm64	yes	Not Apple-notarized; Gatekeeper will prompt on first run
macOS x86_64	yes	Same
Linux x86_64 (gnu)	yes	Needs glibc 2.35 or newer
Linux arm64 (gnu)	yes	Needs glibc 2.35 or newer
Windows	no	cargo install maiden builds, but the Docker sandbox assumes a POSIX shell

The Linux archives link against glibc, so they run on Debian 12+, Ubuntu 22.04+, and similarly recent distributions. On an older glibc — or on a musl distribution such as Alpine — use the container image or cargo install maiden.

Optional tooling

Neither is needed to run an agent, only to author tools:

• cargo-component — for maiden tool build on a Rust tool.
• Node — for maiden tool build on a JavaScript tool.

Docker is needed only if an agent has a sandbox.toml.

Check it works

maiden run my-agent "hello" --mock

--mock uses a scripted provider, so this needs no API key and no network. Next: build your first agent.