How-to guides

Each guide gives every command to paste, in order, and what the command prints. CI runs the commands of each guide against a live server on each change, and fails when a command prints something other than the guide shows. scripts/docs_test.py runs them. See development.

Install and start

• Install: download a release and check it, install with cargo, or build from source, with what each Linux distribution needs first.

• Getting started: the service account, the master key, a certificate, the configuration and the first keys. Then the server is started under systemd or in the foreground.

• Keep vCons in an S3 bucket: RustFS, MinIO or AWS S3 for the sealed objects, the bucket and its key on the storage side, a check that the objects go there and that a purge removes them, what each refusal at start means, and the clean-up. CI runs it with RustFS and with MinIO.

• Keep vCons as Parquet files in a bucket: the objects in the bucket packed into Parquet files, a check that each vCon still reads back, a read with DuckDB, what a purge removes from the bucket and from the storage's disks, and what each refusal means. CI runs it with RustFS.

Use it

• Store your first vCon: store, store again, see a conflict refused, read, list and delete a vCon, with a key for each scope.
• Use keys and scopes: a key for each scope, what each may do and what it is refused, and a key with two scopes.
• Add a second tenant: a tenant made over the admin API, its key, its data kept apart, its retention period, and its removal.

Run it

• Revoke and rotate keys: revoke an API key, replace one without a gap, and rotate the tenant key and the master key.
• Back up and restore: the master key and the data directory, a restore, and what it brings back.
• Export to Parquet: a tenant's vCons as Parquet files in a directory or a bucket, beside a running server, the clear columns each metadata level adds, a read with DuckDB, and what each refusal means.
• Run it in a container: an image built from a checked release, volumes, the memory-lock limit, Docker and Docker Compose.
• Upgrade: a new binary over a running server, the data checked with it, and the way back.

Connect an AI agent

• Connect an AI agent over MCP: a key for the agent, the handshake and the tool list over HTTPS and through vcon-server mcp, and the refusals. The tool list holds the tools the key's scopes allow.
• MCP: the endpoint, the stdio command, the configuration an agent's client reads, and every tool with its parameters and an example.

Source of this page: website/content/docs/how-to.md