GitHub projects, runnable without setup.
A local-first, source-native execution runtime for apps and developer workflows.
Discover. Run. Share. All without leaving your machine.
Install · Quick start · How it works · Safety · Develop
|
Try a repository before you clone, install, or patch your machine. |
Turn a project into a runnable recipe that someone else can inspect and run. |
Record the resolved runtime setup so a run can be inspected and repeated. |
Use the terminal for speed or the desktop app as a visual control plane. |
Ato is a desktop app and command-line runtime for trying local projects, GitHub repositories, and shared app links in a controlled local runtime. It detects what the project needs, prepares missing tools, and runs it without asking you to manually install Python, Node, Rust, or other project-specific dependencies first.
ato run . # run the current project
ato run github.com/owner/repo # try a GitHub repository
ato run https://ato.run/s/demo # open a shared Ato recipeAto is useful when you want to try a repository without reading its setup instructions first, share a runnable project with someone else, run a project with a repeatable setup, or keep the project's runtime separate from your machine as much as possible.
Ato is still pre-1.0. Some sandboxing and network controls are still being completed. See Known limitations before using Ato with untrusted code.
Ato currently focuses on source-native projects and local app recipes.
Default install:
curl -fsSL https://ato.run/install.sh | shOn a graphical macOS or Linux session, the default installer installs Ato Desktop. The Desktop bundle includes the private helper binaries it needs: ato, nacelle, and ato-netd. It does not separately install the standalone CLI archive or expose every helper as a user command.
To also make ato available in your terminal:
curl -fsSL https://ato.run/install.sh | sh -s -- --with-cli--with-cli exposes the bundled ato helper on PATH. It does not download a second copy of ato-cli, and it does not expose nacelle or ato-netd as user-facing commands.
For headless environments, SSH sessions, CI, or CLI-only usage:
curl -fsSL https://ato.run/install.sh | sh -s -- --cli-only--cli-only installs ato plus a private nacelle sidecar. It does not install Ato Desktop.
To install a specific version:
curl -fsSL https://ato.run/install.sh | sh -s -- --version 0.5.5
curl -fsSL https://ato.run/install.sh | sh -s -- --version 0.5.5 --with-cli
curl -fsSL https://ato.run/install.sh | sh -s -- --version 0.5.5 --cli-onlyDefault install:
irm https://ato.run/install.ps1 | iexOn normal Windows desktop sessions, this installs the Ato Desktop MSI. The Desktop bundle includes private ato.exe, nacelle.exe, and ato-netd.exe helpers.
To also make ato available from PowerShell:
irm https://ato.run/install.ps1 | iex -WithCliFor CI, server/headless environments, or CLI-only usage:
irm https://ato.run/install.ps1 | iex -CliOnly-CliOnly installs ato.exe plus a private nacelle.exe sidecar. It does not install Ato Desktop.
brew install ato-run/ato/ato-cliHomebrew installs the CLI, not Ato Desktop.
cargo build -p ato-cli --releaseIf you installed Ato Desktop only, launch Ato Desktop from your applications menu.
If you used --with-cli, -WithCli, --cli-only, -CliOnly, Homebrew, or a source build, verify the terminal command:
ato --helpIf ato is available on PATH:
ato uninstall
ato uninstall --purge
ato uninstall --purge --include-config --include-keys --yesIf you installed Desktop only and did not expose the CLI, remove Ato Desktop through the normal OS app removal flow, or re-run the installer with CLI exposure before using ato uninstall.
The examples below use the ato terminal command. If you installed Desktop only, either run projects from Ato Desktop or reinstall with --with-cli / -WithCli to expose the CLI on PATH.
cd my-project
ato run .Ato inspects the project, prepares the required tools, and starts the app or command. |
ato run github.com/owner/repoUseful for examples, demos, small tools, or projects you do not want to install globally. |
Ato prints the plan and phase progress as it resolves the project, prepares dependencies, and launches the process.
$ ato run github.com/owner/repo
✓ Resolving source
✓ Detecting project type
✓ Preparing runtime
✓ Installing dependencies
✓ Starting project
Running at http://localhost:5173
For a stronger first impression, add a short terminal recording here, for example an Asciinema or GIF showing ato run github.com/owner/repo from command to running app.
ato lock .A lock file records the resolved runtime setup for the project. Commit it when you want other people or CI to run the project the same way.
# Capture the project into a shareable description
ato workspace share
# Materialize a shared project into a local directory
ato workspace setup https://ato.run/s/demo --into ./demoA shared Ato project is represented as a recipe: a portable, inspectable description of source, runtime requirements, entrypoints, state expectations, and policy. In local projects, that recipe is usually written in capsule.toml. In practice, a recipe lets another machine reconstruct the launch without repeating the setup work by hand.
Ato automates the tedious setup of exploring new codebases through four clear steps.
[Source Project]
│
▼
(1) Detect & Resolve ──▶ (2) Lock ──▶ (3) Controlled Runtime ──▶ (4) Capsule / Share
- Detect: Ato inspects the directory or repository to see what kind of project it is, such as Node.js, Python, or Rust.
- Resolve: Ato prepares the required tools and runtimes without modifying your global system as much as possible.
- Lock: Ato records the resolved setup so future runs can be inspected and repeated.
- Run or share: Ato executes the project in a controlled runtime, or captures a runnable description that others can use.
The main file Ato looks for is:
capsule.toml
A capsule.toml describes how source inputs should be arranged, built, configured, and launched. If a project does not have one, Ato can try to infer a basic recipe.
A recipe is the runnable interpretation of a source project. It is not just a package archive and not just a lock file. It ties together enough launch context for Ato to run or reconstruct the project on another machine.
A minimal capsule target can look like this:
[targets.main]
runtime = "source"
driver = "node"
run = "npm run dev"
port = 5173Recipes are useful when you want to share a demo, local app, internal tool, or reproducible workflow without asking every user to manually rediscover the setup.
# Runs the script with the required Python version and dependencies prepared by Ato
ato run ./scripts/report.py# Detects package.json, prepares Node dependencies in isolation, and boots the app
ato run ./examples/web# Builds and runs a Rust workspace member through Ato's runtime path
ato run ./crates/my-tool# Opens a shared Ato recipe from a link
ato run https://ato.run/s/demoAto is not a full replacement for every tool in your stack.
- It is not Docker. It does not require writing a Dockerfile first.
- It is not Nix. It focuses on running and sharing projects, not replacing your whole system environment.
- It is not just
npxoruvx. It can run whole projects, not only single packages. - It is not a remote development environment. It runs locally by default.
Ato sits between these tools: it gives you a fast way to try, lock, and share a project without turning the project into a container image or asking every user to reproduce the setup by hand.
Ato is designed to reduce accidental access to your machine, but it should not be treated as a perfect security boundary yet.
Current behavior:
- project files are run through Ato's runtime path instead of directly on your host
- common secret files such as
.env,.env.*, private keys, and credentials files are excluded from capsule archives by default - some OS-level isolation is available for source runtimes
- deny-all networking is supported for supported runtime paths
Known gaps in the current version:
- hostname allowlists for source runtimes are not fully enforced yet
- missing required environment variables may warn instead of stopping the run
- stricter sandbox mode is not available for every runtime
- some Desktop builds are still beta-quality on non-macOS platforms
Read the full list here:
crates/ato-cli/docs/known-limitations.md
When running code you do not trust, prefer:
ato run github.com/owner/repo --no-buildor inspect the repository first.
ato run . # rehearse a local project in a managed session
ato run github.com/o/r # rehearse a GitHub repository
ato run https://ato.run/s/demo # run a shared recipe
ato install publisher/slug # register a durable local app
ato lock . # generate a lock file
ato workspace share # create a shareable recipe description
ato workspace setup <share> # materialize a shared recipe
ato ps # list running sessions
ato stop --all # stop running sessions
ato logs # show logsThis repository contains the CLI, runtime libraries, desktop app, and supporting tools.
ato/
├── crates/
│ ├── ato-cli/ # command-line interface
│ ├── capsule-core/ # project detection, locking, packing, runtime logic
│ ├── capsule-wire/ # small shared message types
│ ├── ato-session-core/ # session process and state helpers
│ ├── ato-desktop/ # desktop app
│ └── nacelle/ # source runtime sandbox
├── sidecars/
│ └── ato-tsnetd/ # optional network sidecar
├── docs/
│ └── rfcs/ # design notes and proposals
└── .github/workflows/ # CI
Most users should use the installer. Contributors usually work in crates/ato-cli, crates/ato-desktop, capsule-core, and the runtime sidecars.
cargo check --workspace --all-targets
cargo test -p ato-cli
cargo test -p capsule-core
cargo run -p ato-cli -- --helpDesktop bundle examples:
cd crates/ato-desktop
cargo xtask bundle darwin-arm64
cargo xtask bundle windows-x86_64
cargo xtask bundle linux-x86_64Older documentation may refer to ato encap and ato decap. Prefer ato workspace share and ato workspace setup for new examples.
Issues and pull requests are welcome. For larger changes, open an issue first so the runtime, CLI, Desktop, and capsule semantics can be discussed together.
Apache-2.0