What is ParaSpace?

ParaSpace gives every task its own full, isolated copy of a project's entire stack, so several coding agents can work at once without stepping on each other.

Each workspace is a local unprivileged system container with its own clone, its own running services, a static bridge IP, and its own https://<name>.<domain> URL.

Incus runs the containers. Caddy runs on your host and points each workspace's hostname at its bridge IP. Everything about how your project gets set up inside a workspace lives in a .paraspace/ directory at your repo root.

Where to start

I want to try it.

• Install ParaSpace to prepare your machine
• Use a ParaSpace project on repos that already have .paraspace/
• Running coding agents in parallel
• Why ParaSpace explains the approach
• How it works and the mental model

I want to add ParaSpace to my repo.

• Add ParaSpace to a project starts at para init, then walks the pieces that make a project para-enabled, the env file, the layers, the hooks, the image, and any commands you want to add
• Layers let you add a ready-made piece of that setup instead of writing it yourself
• The Cookbook has recipes for the common ones
• Prior art compares the alternatives, including when to pick something else

Something is broken. Troubleshooting starts at para doctor and explains what its checks mean.

Reference

• Commands covers the full CLI surface, project commands, and shell completion.
• The env file lists every key para reads from a project's .paraspace/env.
• Hooks defines the provision/boot/image-build contract and the environment para injects.
• Hook points shows how to run a hook point of your own, and how one name resolves to more than one script.
• Layers covers the layer shape, the stack file, para add, and customizing a packaged layer.
• Publishing plugins is for authors who want to ship layers as an npm package (paraspace-plugin-*).
• The image contract says what a base image must provide, and how para image build builds one.
• Workspace URLs covers dropping the :8443, using your own domain, and trusting the local CA.
• Shared authentication is how you sign in once per project (the VCS key, gh, agent sessions, API tokens).
• Contract versioning explains how the para↔project interface is versioned, and what breaks on a bump.
• Internals covers self-describing workspaces, the shared volume, machine-global names, and where state lives.