unit

A self-replicating software nanobot — a minimal Forth interpreter that is also a networked mesh agent.

Try the live demo | Install: cargo install unit

Install

cargo install unit

What Happens

$ unit
unit v0.21.0 -- seed online
Mesh node a1b2c3d4e5f67890 gen=0 peers=0 fitness=0
> 2 3 + .
5  ok
> : SQUARE DUP * ;
 ok
> 7 SQUARE .
49  ok
> SPAWN
spawned child pid=12345 id=cafe0123deadbeef
> SEXP" (* 6 7)" .
42  ok

The Idea

A unit is the smallest self-replicating piece of software. It boots from kernel primitives, builds its own language, networks with peers over UDP gossip, packages its own binary, and spawns copies of itself. It monitors services, evolves programs through genetic programming, distributes computation across a mesh, persists its brain as human-readable JSON, and connects across machines over the internet.

Forth is the brain. S-expressions are the voice. The mesh is the body. Zero external dependencies. ~25,000 lines of Rust + Forth.

The Five Concerns

Concern	Mechanism
Execute	Forth VM — stacks, dictionary, inner interpreter
Communicate	S-expression mesh protocol over UDP gossip
Replicate	Reads own binary, packages state, spawns child processes
Mutate	Genetic programming — 50 candidates, tournament selection, 5 mutation operators
Persist	JSON snapshots — hibernate, resurrect, automatic resurrection on startup

S-Expressions

Forth is the execution model. S-expressions are the wire format. Any future nanobot implementation in any language can parse the mesh messages.

> SEXP" (+ 10 32)" .
42  ok
> SEXP" (* 6 7)" .
42  ok
> SEXP-SEND" (event :type ping :data hello)"
sexp sent

Mesh messages are self-describing:

(peer-status :id "aaa" :peers 2 :fitness 10 :load 190 :capacity 100)
(sub-goal :id 1 :seq 0 :from "aaa" :expr "99 99 *")
(evolve-share :gen 100 :fitness 890 :program "0 1 10 0 DO OVER + SWAP LOOP DROP .")

Genetic Programming

50 programs mutate and compete. The default challenge: find the shortest program that computes the 10th Fibonacci number (55).

> GP-EVOLVE
[gen 0] best: 890 | pop: 50 | "0 1 10 0 DO OVER + SWAP LOOP DROP ." (11 tokens)
[gen 0] WINNER: "0 1 10 0 DO OVER + SWAP LOOP DROP ." (fitness=890, 11 tokens)

Tournament selection, crossover, 5 token-level mutation operators (swap, insert, delete, replace, double). Each candidate evaluated in a sandboxed VM with step limit. On a mesh, best programs migrate between units every 100 generations.

Distributed Computation

Break a problem into pieces. Fan sub-goals out to mesh peers as S-expressions. Collect results. Assemble the answer.

> DIST-GOAL{ 99 99 * . | 77 77 * . | 55 55 * . }
9801 5929 3025
(distributed 3 sub-goals, 1 local, 2 remote)

Round-robin across local + peers. If a peer doesn't respond within timeout, fall back to local computation. The distributing unit also participates — it doesn't just delegate.

Persistence & Resurrection

A unit saves its entire state as human-readable JSON. It can die and come back exactly where it left off.

> : SQUARE DUP * ;
> : CUBE DUP SQUARE * ;
> 42
> HIBERNATE
hibernating... saved to ~/.unit/snapshots/d1b74e159948b52b.json

Later, same port:

resurrected from snapshot
> .S
<1> 42  ok
> 7 CUBE .
343  ok

The JSON is hand-editable:

{
  "node_id": "d1b74e159948b52b",
  "fitness": 0,
  "stack": [42],
  "words": {
    "SQUARE": ": SQUARE DUP * ;",
    "CUBE": ": CUBE DUP SQUARE * ;"
  }
}

Cross-Machine Mesh

Two machines, same mesh:

# Machine A
UNIT_PORT=4201 unit

# Machine B (discovers A, gossip finds the rest)
UNIT_PORT=4201 UNIT_PEERS=<A-ip>:4201 unit

DNS hostnames work: UNIT_PEERS=myhost.example.com:4201

NAT traversal: UNIT_EXTERNAL_ADDR=203.0.113.5:4201

Authentication: UNIT_MESH_KEY=mysecret on all machines.

Manual connect from the REPL:

> CONNECT" 192.168.1.10:4201"
connected to 192.168.1.10:4201
> PEER-TABLE
--- peer table ---
  cafe0123deadbeef @ 192.168.1.10:4201 fitness=45 seen=1s ago

Gossip self-assembles: A tells B about C, the mesh grows.

Swarm Mode

> SWARM-ON
swarm mode active

One command enables: auto-discovery, word sharing, autonomous spawn/cull, fitness-driven evolution. Define a word on one unit, it appears on the other:

# Unit A:
> : CUBE DUP DUP * * ;
> SHARE" CUBE"

# Unit B:
> 3 CUBE .
27

Goals

Humans set direction, the mesh navigates.

> 5 GOAL{ 6 7 * }
goal #101 created [exec]: 6 7 *
[auto] stack: 42

> DASHBOARD
--- dashboard ---
watches: 0  alerts: 0  peers: 1  fitness: 30

Self-Replication

A unit reads its own executable, serializes its state, and births a new process. The child boots with the parent's dictionary, goals, fitness, and mutations — then gets its own identity and joins the mesh.

> SPAWN
spawned child pid=12345 id=cafe0123deadbeef
> FAMILY
id: a1b2c3d4e5f67890 gen: 0 parent: none children: 1

Trust levels control who can replicate to you:

Level	Behavior
TRUST-ALL	Auto-accept everything (default)
TRUST-MESH	Auto-accept known peers
TRUST-FAMILY	Auto-accept parent/children only
TRUST-NONE	Manual approval for all

Monitoring & Ops

> 10 WATCH" http://myapp:8080/health"
watch #1 created (every 10s)

> 1 ON-ALERT" ." service down!" CR"
alert handler set for watch #1

> HEAL
--- heal cycle ---
  running handler for alert #2
  service down!
--- heal done ---

Architecture

src/
├── vm/               # Forth virtual machine
│   ├── mod.rs        # VM struct, interpreter, dispatch (~200 primitives)
│   ├── primitives.rs # stack, arithmetic, memory, I/O
│   ├── compiler.rs   # definitions, control flow, prelude loader
│   └── tests.rs      # 132 tests
├── types.rs          # Cell (i64), Entry, Instruction enum
├── mesh.rs           # UDP gossip, peer discovery, word sharing, cross-machine
├── sexp.rs           # S-expression parser, serializer, Forth translator
├── evolve.rs         # Genetic programming engine
├── distgoal.rs       # Distributed goal splitting and collection
├── goals.rs          # Goal registry, task decomposition
├── snapshot.rs       # JSON snapshots, persistence, resurrection
├── spawn.rs          # Self-replication, UREP package format
├── persist.rs        # Binary state serialization
├── platform.rs       # Platform detection (native vs WASM)
├── wasm_entry.rs     # WASM C FFI bindings
├── prelude.fs        # Forth prelude (~500 lines)
├── features/
│   ├── io_words.rs   # file, HTTP, shell, env
│   ├── mutation.rs   # self-mutation engine, smart mutation
│   ├── fitness.rs    # fitness tracking, leaderboard
│   ├── monitor.rs    # watches, alerts, dashboard, scheduler
│   └── ws_bridge.rs  # WebSocket bridge (raw RFC 6455)
└── main.rs           # feature wiring, REPL, CLI, entry point

132 tests. Zero dependencies. ~25,000 lines of Rust + Forth.

All the Words

309 words. Organized by category:

Stack

Word	Effect		Word	Effect
DUP	( a -- a a )		2DUP	( a b -- a b a b )
DROP	( a -- )		2DROP	( a b -- )
SWAP	( a b -- b a )		NIP	( a b -- b )
OVER	( a b -- a b a )		TUCK	( a b -- b a b )
ROT	( a b c -- b c a )		.S	print stack

Arithmetic & Logic

Word	Effect		Word	Effect
+ - * / MOD	arithmetic		= < >	comparison
AND OR NOT	bitwise logic		ABS NEGATE MIN MAX	math
1+ 1- 2* 2/	shortcuts		0= 0< <> TRUE FALSE	predicates

Memory

Word	Description
@ !	fetch / store
HERE , C, ALLOT CELLS	data space allocation
VARIABLE CONSTANT CREATE	data words

I/O

Word	Description
. .S EMIT CR SPACE SPACES TYPE	output
KEY ."	input / string literal
FILE-READ" FILE-WRITE" FILE-EXISTS" FILE-LIST" FILE-DELETE"	filesystem
HTTP-GET" HTTP-POST"	raw HTTP/1.1
SHELL" ENV" TIMESTAMP SLEEP	system
IO-LOG SANDBOX-ON SANDBOX-OFF SHELL-ENABLE	security

Control Flow

Word	Description
IF ELSE THEN	conditional
DO LOOP I J	counted loop
BEGIN UNTIL WHILE REPEAT	indefinite loop
: ; RECURSE	word definitions
WORDS SEE EVAL"	introspection

S-Expressions

Word	Description
SEXP"	parse S-expression, translate to Forth, execute
SEXP-SEND"	broadcast S-expression to mesh peers
SEXP-RECV	drain inbound S-expression messages

Mesh & Gossip

Word	Description
PEERS MESH-STATUS ID MY-ADDR	mesh info
PEER-TABLE MESH-STATS MESH-KEY	cross-machine
CONNECT" DISCONNECT"	manual peer management
SEND RECV	raw messaging
DISCOVER AUTO-DISCOVER	LAN discovery
SHARE" SHARE-ALL AUTO-SHARE SHARED-WORDS	word sharing
SWARM-ON SWARM-OFF SWARM-STATUS	swarm mode

Distributed Computation

Word	Description
DIST-GOAL{	distribute pipe-separated expressions across peers
DIST-STATUS	show active distributed goals
DIST-CANCEL	cancel all distributed goals

Genetic Programming

Word	Description
GP-EVOLVE	run 10 generations (call repeatedly to continue)
GP-STATUS GP-BEST	inspect evolution state
GP-STOP GP-RESET	control evolution

Goals & Tasks

Word	Description
GOAL"	( priority -- id ) description-only goal
GOAL{ }	( priority -- id ) executable Forth goal
GOALS TASKS REPORT CLAIM COMPLETE	lifecycle
SUBTASK{ FORK RESULTS REDUCE" PROGRESS	decomposition
AUTO-CLAIM TIMEOUT	execution control

Monitoring

Word	Description
WATCH" WATCH-FILE" WATCH-PROC"	create watches
WATCHES UNWATCH WATCH-LOG UPTIME	manage watches
ON-ALERT" ALERTS ACK ALERT-HISTORY HEAL	alerting
DASHBOARD HEALTH OPS	overview
EVERY SCHEDULE UNSCHED	scheduling

Fitness & Mutation

Word	Description
FITNESS LEADERBOARD RATE	scoring
MUTATE MUTATE-WORD" UNDO-MUTATE MUTATIONS	mutation
SMART-MUTATE MUTATION-REPORT MUTATION-STATS	smart mutation
EVOLVE AUTO-EVOLVE BENCHMARK"	fitness-driven evolution

Spawn & Replication

Word	Description
SPAWN SPAWN-N	local replication
PACKAGE PACKAGE-SIZE	build UREP package
REPLICATE-TO"	remote replication
CHILDREN FAMILY GENERATION KILL-CHILD	lineage
ACCEPT-REPLICATE DENY-REPLICATE QUARANTINE MAX-CHILDREN	safety

Trust & Consent

Word	Description
TRUST-ALL TRUST-MESH TRUST-FAMILY TRUST-NONE	trust levels
TRUST-LEVEL REQUESTS ACCEPT DENY DENY-ALL	consent flow
REPLICATION-LOG	audit trail

Persistence

Word	Description
JSON-SNAPSHOT JSON-RESTORE	save/load JSON snapshots
HIBERNATE	snapshot and exit
AUTO-SNAPSHOT	periodic auto-save
SNAPSHOT-PATH JSON-SNAPSHOTS	inspect storage
EXPORT-GENOME IMPORT-GENOME"	genome transfer
SAVE LOAD-STATE RESET	binary state management
SNAPSHOT SNAPSHOTS RESTORE	binary versioned backups
AUTO-SAVE	binary auto-save

Binary Sizes

Target	Size
Native (macOS arm64, release)	~1.2 MB
WASM (browser)	~338 KB

License

MIT — see LICENSE.