Social cloud hosting
1# at-rund
2
3> **⚠️ HEAVILY UNDER CONSTRUCTION**
4>
5> This project is in early alpha. APIs will change, features are incomplete, and you will encounter bugs. See [ROADMAP.md](./ROADMAP.md) for current status.
6
7**Social cloud hosting for AT Protocol.**
8
9at-rund lets you host serverless bundles for the AT Protocol network. Your runner represents *you* — bundle authors trust your infrastructure because they trust you.
10
11## The Idea
12
13Today, running code on the internet means trusting faceless cloud providers. at-rund flips this: anyone can host a runner, and trust flows through the social graph.
14
15```
16┌─────────────────────────────────────────────────────────────────────────────┐
17│ Social Cloud Hosting │
18│ │
19│ "I run an at-rund instance. Trust me because you know me." │
20│ │
21├─────────────────────────────────────────────────────────────────────────────┤
22│ │
23│ @alice.bsky.social @bob.example.com │
24│ runs at-run.alice.dev runs compute.bob.example.com │
25│ ├─ deno + ffmpeg ├─ deno │
26│ ├─ python + pytorch ├─ node │
27│ └─ allowlist: friends └─ open to all │
28│ │
29│ Bundle authors choose runners based on: │
30│ • Social trust (I know Alice) │
31│ • Capabilities (Alice has ffmpeg) │
32│ • Availability (Bob's is always up) │
33│ │
34└─────────────────────────────────────────────────────────────────────────────┘
35```
36
37## How It Works
38
391. **Bundle authors** write serverless functions and store them on their AT Protocol PDS
402. **Runners** (like you) host at-rund instances that execute those bundles
413. **Trust** is social — authors choose runners they trust, runners choose who can use them
42
43```
44Bundle Author Runner Host
45 │ │
46 │ 1. Write bundle │
47 │ 2. Deploy to PDS │
48 │ 3. Encrypt secrets for runner │
49 │ │
50 └──────────── request ───────────────▶│
51 │ 4. Fetch bundle from PDS
52 │ 5. Execute in sandbox
53 │ 6. Return result
54 ◀─────────── response ────────────────┘
55```
56
57## Quick Start
58
59### Install
60
61```bash
62# Download at-rund
63curl -sSL https://at-run.dev/install.sh | sh
64
65# Install Nix (required for runtimes)
66curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh
67```
68
69### Initialize
70
71```bash
72at-rund init
73```
74
75This creates `~/.at-rund/` with default configuration and runtime definitions.
76
77### Configure
78
79Edit `~/.at-rund/config.toml`:
80
81```toml
82# Your identity — the runner IS you
83did = "did:plc:your-did-here"
84handle = "you.bsky.social"
85
86port = 3000
87
88[access]
89# Who can use your runner?
90# "open" - anyone
91# "allowlist" - only specific DIDs
92# "blocklist" - everyone except specific DIDs
93mode = "open"
94
95[runtimes]
96# Which runtimes you support
97deno = "deno.nix"
98```
99
100### Run
101
102```bash
103# Development (uses Nix directly, no VM isolation)
104at-rund serve --dev
105
106# Production (uses Firecracker VMs, requires Linux + KVM)
107at-rund build # Build VM images
108at-rund serve # Start server
109```
110
111### Deploy as a Service
112
113```bash
114# Install systemd service
115at-rund systemd install
116
117# Start and enable
118sudo systemctl enable --now at-rund
119
120# Check status
121at-rund systemd status
122```
123
124## Architecture
125
126at-rund supports multiple isolation backends to balance security vs. accessibility:
127
128```
129┌─────────────────────────────────────────────────────────────┐
130│ at-rund │
131│ Executor interface │
132├───────────────┬───────────────────┬─────────────────────────┤
133│ NixPool │ ContainerPool │ FirecrackerPool │
134│ (none) │ (container) │ (firecracker) │
135├───────────────┼───────────────────┼─────────────────────────┤
136│ Direct exec │ Docker/Podman │ Firecracker microVMs │
137│ No isolation │ Namespace + seccomp│ Full VM isolation │
138│ Any OS │ Any Linux VPS │ Linux + KVM (bare metal)│
139│ Dev/testing │ Production │ High-security prod │
140└───────────────┴───────────────────┴─────────────────────────┘
141```
142
143### Isolation Modes
144
145Configure via `isolation` in config.toml:
146
147```toml
148# Auto-detect best available (default)
149isolation = "auto"
150
151# Or explicitly choose:
152isolation = "none" # Direct Nix execution (dev mode)
153isolation = "container" # OCI containers (debian-slim + seccomp)
154isolation = "firecracker" # Firecracker microVMs (requires KVM)
155```
156
157**Auto-detection logic:**
1581. `/dev/kvm` accessible → Firecracker
1592. Docker/Podman available → Container
1603. Fallback → Nix direct execution
161
162### Why Multiple Backends?
163
164- **Low barrier to entry**: Containers work on any $5 VPS
165- **Strong isolation available**: Firecracker for those with bare-metal
166- **Same bundle everywhere**: Nix ensures identical runtimes across all backends
167- **Operator choice**: Match isolation level to your threat model
168
169See [DESIGN.md](./DESIGN.md) for detailed architecture decisions.
170
171## Custom Runtimes
172
173Runtimes are defined with Nix. You can customize the defaults or create your own:
174
175```nix
176# ~/.at-rund/runtimes/python-ml.nix
177{ pkgs, ... }:
178{
179 mimeTypes = [
180 "application/python+ml"
181 ];
182
183 guest = {
184 environment.systemPackages = with pkgs; [
185 python312
186 python312Packages.pytorch
187 python312Packages.numpy
188 python312Packages.pillow
189 ];
190 };
191
192 executor = {
193 command = "python3";
194 permissionFlags = {};
195 };
196}
197```
198
199Then enable it in your config:
200
201```toml
202[runtimes]
203deno = "deno.nix"
204python-ml = "python-ml.nix"
205```
206
207## Access Control
208
209Control who can run bundles on your infrastructure:
210
211```toml
212[access]
213# Open to everyone
214mode = "open"
215
216# Only allow specific people
217mode = "allowlist"
218allowlist = [
219 "did:plc:friend1",
220 "did:plc:friend2",
221]
222
223# Block bad actors
224mode = "blocklist"
225blocklist = [
226 "did:plc:spammer",
227]
228```
229
230For more complex policies (payments, quotas, rate limiting), put a reverse proxy in front of at-rund.
231
232## Observability
233
234at-rund supports OpenTelemetry for metrics and traces:
235
236```toml
237[observability]
238otlp_endpoint = "http://localhost:4317"
239log_format = "json"
240```
241
242This lets you connect to Grafana, Jaeger, or any OTLP-compatible backend.
243
244## CLI Reference
245
246```
247at-rund
248├── init Initialize ~/.at-rund/
249├── serve Run the server
250│ ├── --dev Dev mode (Nix direct execution)
251│ ├── --port PORT Override port
252│ └── --config PATH Custom config path
253├── build Build Firecracker VM images
254│ └── --runtime NAME Build specific runtime only
255├── runtime
256│ └── list Show configured runtimes
257├── pool
258│ ├── status VM pool statistics
259│ ├── warm Pre-warm VMs
260│ └── drain Graceful shutdown
261└── systemd
262 ├── install Install systemd service
263 │ └── --user User service (no sudo)
264 ├── uninstall Remove service
265 └── status Show service status
266```
267
268## Project Structure
269
270```
271~/.at-rund/
272├── config.toml # Main configuration
273├── runtimes/ # Nix runtime definitions
274│ ├── deno.nix
275│ ├── node.nix
276│ └── python.nix
277├── images/ # Built Firecracker images (prod)
278├── bundles/ # Cached bundle code
279└── keys/ # Runner keypair (for secrets)
280```
281
282## Related Projects
283
284- **[at-run](https://github.com/neutrino2211/at-run)** — Developer CLI for deploying bundles
285- **[AT Protocol](https://atproto.com)** — Decentralized social protocol
286- **[Firecracker](https://firecracker-microvm.github.io/)** — Lightweight virtualization
287- **[Nix](https://nixos.org)** — Reproducible builds
288
289## License
290
291MIT