totopo 3.0.0 → 3.0.1-rc-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
<img src=".github/assets/logo.png" alt="totopo" width="100%" />
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Local sandbox for AI agents.
|
|
6
6
|
|
|
7
7
|
|
|
8
8
|
|
|
@@ -10,28 +10,50 @@ Run AI coding agents in a secure local sandbox.
|
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Motivation
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Two fundamental issues with AI agents:
|
|
16
|
+
- They are non-deterministic — they will occasionally get things wrong.
|
|
17
|
+
- They are susceptible to prompt injection — they can get compromised and act against your interests without you knowing.
|
|
16
18
|
|
|
17
|
-
totopo
|
|
19
|
+
totopo addresses both with a dev container - when you run totopo in a given directory, the directory is mounted as a workspace where agents get a full, capable environment to work in — they just can't touch anything outside the workspace, and they can't reach remote git repositories.
|
|
20
|
+
|
|
21
|
+
If an agent makes a mistake, damage is contained to the workspace; your git remote is out of reach.<br>
|
|
22
|
+
If an agent gets compromised, it can't reach your host files — blast radius is limited to the workspace you chose to share.
|
|
23
|
+
|
|
24
|
+
> totopo's security approach is basic — it is about the minimal precautions I believe anyone running AI agents should have. If you need more robust protections, look somewhere else.
|
|
18
25
|
|
|
19
26
|
## Requirements
|
|
20
27
|
|
|
21
28
|
- [Docker](https://www.docker.com/products/docker-desktop/) — builds and runs the dev container
|
|
22
29
|
- [Node.js](https://nodejs.org/) — required to run `npx totopo`
|
|
23
30
|
|
|
24
|
-
##
|
|
31
|
+
## Quick Start
|
|
25
32
|
|
|
26
33
|
```bash
|
|
27
34
|
cd your-project
|
|
28
35
|
npx totopo
|
|
29
36
|
```
|
|
30
37
|
|
|
31
|
-
`npx totopo` always runs the latest stable version
|
|
38
|
+
`npx totopo` always runs the latest stable version. Alternatively, install globally to pin a specific version: `npm install -g totopo`.
|
|
32
39
|
|
|
33
40
|
> **Do not install totopo as a local project dependency.** totopo stores all workspace state in `~/.totopo/`, shared across all your workspaces. A local install means different projects could run different versions, which can break schema compatibility with shared config. Use `npx` or a global install.
|
|
34
41
|
|
|
42
|
+
### Basic Usage
|
|
43
|
+
|
|
44
|
+
Once set up, the flow is simple:
|
|
45
|
+
|
|
46
|
+
1. Run `npx totopo` → **Open session**
|
|
47
|
+
2. Run `claude`, `opencode`, or `codex` — pick an agent, start working
|
|
48
|
+
|
|
49
|
+
A few things happen automatically:
|
|
50
|
+
|
|
51
|
+
- **Agents stay up to date** — when you open a session, totopo ensures all AI CLIs are on their latest version.
|
|
52
|
+
- **Sessions are persistent** — agent memory and settings survive container restarts and rebuilds.
|
|
53
|
+
- **Your machine stays safe** — the container can't push to remote, can't read outside the workspace, and sensitive paths like `.env` can be hidden from agents entirely (see [Shadow Paths](#shadow-paths)).
|
|
54
|
+
|
|
55
|
+
For a deeper look at how totopo works and how to configure it, see the sections below.
|
|
56
|
+
|
|
35
57
|
## How totopo Works
|
|
36
58
|
|
|
37
59
|
totopo organises work around **workspaces** — any directory containing a `totopo.yaml` file. Running `npx totopo` for the first time in a directory walks you through a short setup and creates `totopo.yaml` (a small, well-documented config file that lives at the workspace root).
|
|
@@ -51,7 +73,7 @@ On every run, totopo shows the workspace menu:
|
|
|
51
73
|
|
|
52
74
|
### Working directory
|
|
53
75
|
|
|
54
|
-
The workspace is always mounted at `/workspace` inside the container. When you run totopo from a subdirectory, you get a quick prompt to start **here** or at the **
|
|
76
|
+
The workspace is always mounted at `/workspace` inside the container. When you run totopo from a subdirectory, you get a quick prompt to start **here** or at the **workspace root**. If you're already at the workspace root, the session starts directly at `/workspace`.
|
|
55
77
|
|
|
56
78
|
## Core Features
|
|
57
79
|
|