How jamsocket/forevervm works
Project type and purpose
• From the README and file tree, this is an open-source, polyglot SDK + CLI toolset (“foreverVM”) for running stateful Python code via a remote API.
• It provides:
• Language-specific CLI clients (JavaScript, Rust)
• Language-specific SDKs (JavaScript, Python, Rust)
• Example apps (JS example, JS “mcp-server”)
• CI/CD & publishing scripts
File structure
• Top-level directories by language:
• javascript/ ← contains a CLI (forevervm), an SDK (@forevervm/sdk), an example client, a “mcp-server” sample microservice
• python/ ← contains a forevervm CLI wrapper and an SDK package (forevervm_sdk) + tests
• rust/ ← contains two crates: forevervm (CLI) and forevervm-sdk (library)
• scripts/ ← bump-version & publish tooling (TypeScript)
• .github/workflows/ ← per-language build/test/publish pipelines
• Root publishing.md, LICENSE, README
README for architectural insights
• Core concepts: Machines (stateful Python processes), Instructions (code you send, one at a time)
• The user interacts via CLI or SDK -> sends REST/WebSocket calls to a remote foreverVM API.
• The API manages machine lifecycle, memory limits, tags, swap to disk, etc.
Main components to capture
a. Developer’s workspace / Monorepo
– Code modules: JS SDK, JS CLI, Rust SDK, Rust CLI, Python SDK, Python CLI, Example, mcp-server, Publish scripts
– CI/CD pipelines (GitHub Actions)
b. Package registries & distribution
– npm registry (forevervm, @forevervm/sdk)
– PyPI (forevervm)
– crates.io (forevervm, forevervm-sdk)
c. End user applications
– CLI commands (e.g. npx forevervm, forevervm repl)
– Embedded SDK code in user apps
– Example apps (JS example, mcp-server)
d. External foreverVM API service (hosted)
– Authentication (API token)
– REST or WebSocket endpoints: createMachine, listMachines, exec instr, stream output
– Backend sub-system (not in this repo): machine manager, container/Python process pool, swap-to-disk store
Relationships and interactions
• Developers push code → GitHub Actions → run per-language tests → on success → scripts/publish → push packages to registries
• End users install CLI/SDK from registries → instantiate ForeverVM client → authenticate → connect to remote foreverVM API
• foreverVM API orchestrates machines & returns results over HTTP/WebSocket
Architectural patterns & design principles
• Monorepo with language-specific packages, shared version bump/publish scripts
• Single logical API boundary, multiple SDK adapters (Adapter pattern)
• CI/CD pipeline per language, unified publishing flow
Detail level
• Every language implementation as its own module if space allows
• Don’t overthink—break system into as many logical components as makes the flow clear
A) Developer/Repo Layer: Monorepo → language packages + scripts + CI/CD
B) Distribution Layer: npm, PyPI, crates.io registries
C) Runtime Layer: End-user apps (CLI/SDK) → foreverVM API → machine management backend