# tartarus
Tartarus is tool designed to make it easier to launch processes in sandboxes.
The primary rationale for the development was frustration around agents (including within editors) not having particularly robust configurations for permissions local to a project.
## Why "Tartarus"?
From [Wikipedia](https://en.wikipedia.org/wiki/Tartarus) (on June 6, 2026 at least):
> In Greek mythology, Tartarus is the deep abyss that is used as a dungeon of torment and suffering for the wicked and as the prison for the Titans
Whether AI tools belong here or not is a question that we all have to decide for ourselves.
## CLI
The most straightforward way to use Tartarus is via the CLI tool, which has built-in logic for several common use cases.
### Installation
`tartarus` can be installed via `cargo`:
```bash
cargo install tartarus
```
### Usage
```bash
Usage: tartarus <COMMAND>
Commands:
list List all sandboxes in the configuration file
exec Execute a process inside a sandbox
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
```bash
Usage: tartarus exec [OPTIONS] <PROCESS> [ARGS]...
Arguments:
<PROCESS> The process to invoke inside the sandbox
[ARGS]... The arguments to pass to the sandboxed process
Options:
-n, --dry-run Print out the full command that would have been executed instead of running it
-s, --sandbox <SANDBOX> The name of the configuration to use
-h, --help Print help
```
### Configuration
Sandboxes can be configured via `~/.config/tartarus/config.toml`.
```toml
# `sandboxes.<name>` declares a sandbox with the given name.
[sandboxes.zed_rust_dev]
# Currently, the only supported type of sandbox is "bubblewrap".
# In the future, other sandbox types are planned (e.g. `sandbox-exec` for MacOS).
type = "bubblewrap"
# Optional (default: false)
allow_network_access = true
# The directory to run the sandbox from.
#
# Optional (default: the directory where `tartarus` was invoked from)
working_dir = "/home/user/projects/some-rust-project"
# Directories to make writable inside the sandbox. The root directory is mounted as read-only, so any changes outside of
# the directory where `tartarus` is invoked from or one of the directories specified in `writable_dirs` will fail with permission errors.
#
# Optional (default: [])
writable_dirs = [
"/home/user/log-files",
]
# Directories to pass through directly from the host to a fake home directory used by the sandbox.
#
# Each entry is a path relative to the home directory of the user invoking the sandbox.
#
# Optional (default: [])
passthrough_home_dirs = [
".cache",
".local/share",
".cargo",
".rustup",
]
## Section: overrides
#
# Declares a set of overrides for files under the home directory.
#
# Per TOML specification, using `[[...]]` allows multiple separate instances to concatenate into a single array.
# The path relative to the home directory of the user invoking the sandbox.
#
# The directory will be copied into the sandbox's fake home directory as-is, with potential
# modifications made via overrides below. Specific files can be overridden with custom settings to overwrite the ones
# in the real home directory.
# Zed configuration: override the tool permissions to allow arbitrary usage in the sandbox.
[[sandboxes.zed_rust_dev.override_home_dirs]]
subpath = ".config/zed"
[[sandboxes.zed_rust_dev.override_home_dirs.overrides]]
file = "settings.json"
[sandboxes.zed_rust_dev.override_home_dirs.overrides.type.Zed]
tool_permission = "Allow"
# OpenCode configuration: allow arbitrary access to external directories in the sandbox.
[[sandboxes.zed_rust_dev.override_home_dirs]]
subpath = ".config/opencode"
[[sandboxes.zed_rust_dev.override_home_dirs.overrides]]
file = "opencode.jsonc"
[sandboxes.zed_rust_dev.override_home_dirs.overrides.type.OpenCode]
external_directories = "Allow"
# Arbitrary overrides can be specified via a custom shell commands.
#
# External tool override commands should accept the path to a file with the contents of the original file, which should be modified
# to reflect the state the file should have inside the sandbox.
#
# Note that this does *not* affect the contents of the file outside the sandbox; the file being modified is a temporary copy of the original file.
[[sandboxes.zed_rust_dev.override_home_dirs]]
subpath = ".config/nushell"
[[sandboxes.zed_rust_dev.override_home_dirs.overrides]]
file = "config.nu"
[sandboxes.zed_rust_dev.override_home_dirs.overrides.type.ExternalTool]
name = "add-some-stuff"
[[sandboxes.zed_rust_dev.override_home_dirs.overrides]]
file = "env.nu"
[sandboxes.zed_rust_dev.override_home_dirs.overrides.type.ExternalTool]
name = "add-some-other-stuff"
# Default command to run when no command is specified
[sandboxes.zed_rust_dev.default_command]
name = "zed"
# Optional (default: [])
args = ["."]
```
## Rust API
`tartarus` can also be used as a Rust library via the `tartarus-api` crate. The APIs provide the ability to configure and execute sandboxes above, but with the additional ability to specify arbitrary overrides via implementation of the `Override` trait.
* [crates.io link](https://crates.io/crates/tartarus-api)
* [API documentation](https://docs.rs/tartarus-api)