Documentation

Each page below is written against the code in the repository. Where a feature is still being built, the page says so.

• What is builtWhich parts of vcon-server work today, and which are being built.
• RoadmapThe next milestones for vcon-server.
• How-to guidesStep-by-step guides for installing and running vcon-server. Each shows every command and its output, and CI runs each against a live server.
• InstallPut the vcon-server binary on a Linux host: download a release and check it, install it with cargo, build it from source, or run it in a container. Each path lists what to install first on Debian, Ubuntu and Fedora, what each step prints, and what to do when a step fails.
• Getting startedFrom an installed binary to a running server: the service account, memory locking, the master key, a certificate, the configuration, the first tenant and its keys, and the server started under systemd or in the foreground.
• Keep vCons as Parquet files in a bucketTurn on Parquet storage over an S3 bucket: what the bucket must be, the configuration, a check that the server packs its objects into Parquet files and still reads each vCon back, a read of the files with DuckDB, what a purge removes from the bucket and from the storage's disks, and what each refusal means.
• Keep vCons in an S3 bucketKeep each version's sealed object in an S3-compatible bucket (RustFS, MinIO or AWS S3) instead of the data directory: the bucket and its keys on the storage side, the configuration, a check that the objects go there and that a purge removes them, what each refusal means, and how to clean up.
• Export to ParquetWrite a copy of a tenant's vCons as Parquet files, to a directory or an S3 bucket, beside a running server: choose which clear columns the files carry, read them with DuckDB, check the export, and see what each refusal means.
• Store your first vConA first vCon end to end: store it, store it again, see a conflict refused, read it back byte for byte, list it, and delete it, each with a key that holds only the scope it needs, and every answer shown.
• Use keys and scopesMake a key for each scope, see what each one may do and what it is refused, and make a key with more than one scope. Every request and its answer is shown.
• Add a second tenantMake a second tenant over the admin API while the server runs, give it a key, see that its data and acme's stay apart, change its retention period, and remove it.
• Revoke and rotate keysRevoke an API key over HTTP or on the host, replace a key without a gap, and rotate a tenant's key and the master key, with every command and its output.
• Back up and restoreBack up the master key and the data directory while the server runs, restore the data directory, check it, and see what a restore brings back, revoked keys included.
• Run it in a containerBuild a container image from a checked release, keep the configuration and the data in volumes, allow the server to lock its memory, make the first keys, run it, back it up, and stop it, with Docker or Docker Compose.
• UpgradeMove a running server to a newer release: check the new binary, stop the server, copy the data directory, install the binary, check the data with it, start it, and go back to the old version if you need to.
• Connect an AI agent over MCPGive an AI agent its own key, then check the MCP endpoint by hand: the handshake and the tool list over HTTPS, the refusals, and the same through vcon-server mcp.
• ConfigurationEvery key of the configuration file, its default, and why the default is what it is.
• Tenants and keysHow tenants keep their data apart, what each key scope allows, and how keys are made and revoked.
• Storing vConsWhat vcon-server accepts, what it checks, how versions, deletes and replaces work, and what it never does to a vCon.
• Retention and legal holdsHow long a deleted vCon is kept, when it is erased, how a legal hold stops that, and what the legal routes can read and restore.
• Audit logsWhat vcon-server records about each request, where, and what it never records.
• SecurityThe key hierarchy, what is encrypted with what, how the process protects keys in memory, and what an attacker gets from each thing they might steal.
• Assurance caseWhy vcon-server's security requirements are met: the threat model, the trust boundaries, how the design principles are applied, and how the common weaknesses are countered.
• HTTP APIEvery route: the scope it needs, what it takes, and what it answers.
• Client examplesPrograms in curl, Python, TypeScript, Go and Rust that work through the HTTP API and MCP: store, gzip, list with a cursor, replace, legal hold, audit, admin and MCP calls, and delete.
• ConsoleOpen the web console the server serves, sign in with an API key, and what the console does and does not keep.
• The vcon libraryRead, check and write vCons in your own Rust code with the vcon crate.
• MCPConnecting an AI agent to vcon-server over MCP, and every tool with its parameters and an example.
• ProducersSending vCons to vcon-server from a recorder, a conserver or any other producer: keys, retries, and what each answer means.
• OperationsRunning vcon-server day to day: the data directory, what may run beside the server, the purge sweep, logs, health checks and backups.
• Command lineEvery vcon-server command: what it does, what it prints, its exit codes, and which may run beside a serving server.
• DevelopmentThe code's layout, how it is tested, the gates every commit passes, and how to work on this site.