From 263985a5861f93413b1cecf4dd9aab03e745be6f Mon Sep 17 00:00:00 2001 From: Kawah Date: Thu, 25 Jun 2026 11:47:51 +0200 Subject: [PATCH 1/5] smalle dit --- README.md | 140 ++++++++++++++++++++---------------------------------- 1 file changed, 52 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 08e9253f..bdb9d27f 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,98 @@ # GSV -![gsv](https://github.com/user-attachments/assets/fd40032c-d551-44e4-ba77-7808d29cc0a1) -> ***A computer for humans and machines.*** -Imagine a personal cloud computer where AI is built directly into the kernel. **GSV (General Systems Vehicle)** unifies your laptops, servers, and phones into a single cohesive system where agents operate as native background processes. +![gsv](https://github.com/user-attachments/assets/fd40032c-d551-44e4-ba77-7808d29cc0a1) -Named after the planet-scale sentient ships from Iain M. Banks' *Culture* series, GSV provides the foundation for self-aware personal AI that lives, breathes, and spawns across the edge of the internet. +> ***A mind for your machines, by [Humans & Machines, Inc.](https://humanandmachin.es)*** -> [!NOTE] -> **GSV is actively baking! 🏗️** -> We are polishing the final touches for our official beta launch in the upcoming weeks. We believe in transparent, open-source development, so you are incredibly welcome to deploy it and play with it exactly as it is today. Expect rapid changes, a few broken wires, and frequent updates! +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) +[![Release](https://img.shields.io/github/v/release/deathbyknowledge/gsv)](https://github.com/deathbyknowledge/gsv/releases) +[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/hy9ExJJFvn) +[![X](https://img.shields.io/badge/X-@humachinesinc-000?logo=x&logoColor=white)](https://x.com/humachinesinc) +[![Website](https://img.shields.io/badge/site-gsv.space-111)](https://gsv.space) +[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/deathbyknowledge/gsv) -## What can GSV do? +**🛸 Public beta — coming before July. Issues and PRs very welcome.** -- **Treat Agents like Linux Processes** - Agents have identities, durable history, permissions, and a syscall surface. You can spawn, kill, and manage them just like traditional OS processes. -- **Unify Your Hardware** - Connect your Macbook, Linux server, or phone. Your agents can securely reach your devices, use the shell, and read/write files from anywhere on Earth or beyond. -- **Communicate Natively** - Talk to your agents via the built-in Web UI, the command-line interface, or bridge them to external channels like WhatsApp and Discord. -- **A Self-Hosting Ecosystem** - Write native apps with the GSV SDK and distribute them via the built-in git remote. Because agents can own repositories and host their own packages, GSV functions as a distributed, peer-to-peer app store. +Most personal AI agents run on one host you pick and keep alive — a laptop, a VPS, a container. GSV turns all your devices into a single computer. It spans your laptop, server, and phone at once, lets an agent act on whichever one fits, and runs on the edge in your own Cloudflare account; your keys, your data, no host to provision or babysit. From ~$5/mo infra plus your own model costs. -## Documentation -- [Documentation page](https://gsv.space/) -- [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/deathbyknowledge/gsv) +## What you can do -## 🤝 Get Involved +- Run things across all your machines from one agent — kick off a job on your home server while your laptop's shut. +- Keep agents working while your devices sleep — they live on the edge, not your hardware. +- Reach it from anywhere — web UI, CLI, or Discord / Telegram. +- Spawn durable agents with their own memory, permissions, and the ability to start sub-agents. +- Host your own packages and share apps between GSV instances through a built-in git remote. -GSV is actively evolving, and we want you to be part of the network! We welcome contributions of all sizes. -Whether you want to submit a pull request, share a wild idea, or just say hi, please don't hesitate to reach out. :) - -- **Join the Community:** Come hang out, talk shop, and share ideas on our [Discord Server](https://discord.gg/hy9ExJJFvn). -- **Found a bug or have a feature request?** - [Open an issue](https://github.com/deathbyknowledge/gsv/issues). -- **Follow Updates:** Reach out directly on Twitter/X: [@deathbyknowledg](https://x.com/deathbyknowledg) or [@humachinesinc](https://x.com/humachinesinc) -- **Direct Feedback & Support:** Of course, you can also just email us at **[hello@humansandmachin.es]** to share your thoughts or get help. +Under the hood it's a distributed OS: agents are durable processes with identities, history, permissions, and a syscall surface, plus an SDK for building apps. Named after the sentient ships from Iain M. Banks' Culture series, GSV (General Systems Vehicle) is a foundation for personal AI that lives across the edge. ## Quick Start -### Prerequisites +Prerequisite: a [Cloudflare account](https://dash.cloudflare.com/sign-up) on the Workers Paid plan ($5/month). -- [Cloudflare account](https://dash.cloudflare.com/sign-up) (Workers Paid plan required) + + +```bash +# Install CLI curl -sSL https://install.gsv.space | bash -# Deploys all components to your Cloudflare account +# Deploy all components to your Cloudflare account gsv infra deploy --api-token -# For a second install in the same account, add a unique instance prefix: -gsv infra deploy --instance gsv-personal --api-token ``` -Once the deployment finishes, open the URL to finish your onboarding through the Web UI. - -### Chat - -You can interact with any of the Agent processes in your GSV in multiple ways: - -- Through the built-in **Chat** app in the web UI -- By messaging through any connected adapter, such as WhatsApp, Discord, or Telegram -- Or through the CLI directly: +Open the URL it prints to finish onboarding in the Web UI. Then chat from the UI, a connected adapter (Discord/Telegram), or the CLI: ```bash gsv chat "Hello, what can you help me with?" ``` -### Connect a Device -Devices connected to your GSV user are reachable by your agents from anywhere on Earth. +## Connect a Device -Easily add a device through **GSV > Devices** in the Web UI or do it directly from the CLI: +Connected devices are reachable by your agents from anywhere — outbound-only, so no open ports, no inbound connections, no VPN. Add one via **GSV > Devices** in the Web UI, or the CLI: ```bash -# Create a token for the device (make a note of it) -gsv auth token create --device macbook --label Macbook -# Set the token +gsv auth token create --device macbook --label Macbook # note the token gsv config --local set node.token -# Manual install/start as a background service: -gsv device install --id macbook --workspace ~/ - -# Check status/logs +gsv device install --id macbook --workspace ~/ # background service gsv device status -gsv device logs --follow - -# Instead of a background service you can run it in the foreground: -gsv device run --id macbook --workspace ~/projects ``` -Node logs are structured JSON at `~/.gsv/logs/node.log` with app-side rotation -(default: 10MB, 5 files). Override with `GSV_NODE_LOG_MAX_BYTES` and -`GSV_NODE_LOG_MAX_FILES`. +Now GSV can use the shell and read/write files on that machine. Set up adapters under **GSV > Integrations**. -Now GSV can use the shell, read and write files on your machine. +## OS Model -## Adapters +Linux-like by design, so agents can reason with familiar patterns (mental model, not POSIX). -The easiest way to set up adapters is through **GSV > Integrations** in the Web UI. - -## Components - -- **Gateway** - Central brain running on Cloudflare, serves as the OS kernel. Manages auth, filesystem state, routing, and exposes system calls that processes and apps use to access GSV capabilities. -- **Processes** - Each agent is a process in the GSV OS with persistent history and its own agent loop. -- **Devices** - Your devices connected to GSV, providing remote tool access (Bash, Read, Write, Edit, Search). -- **Adapters** - Bridges to WhatsApp, Discord, Telegram, etc. Each runs as a separate Worker. +- **Kernel** — the Gateway runs on Cloudflare, exposing authenticated syscalls (`proc.*`, `pkg.*`, `sys.*`). +- **Processes** — agents are durable processes with PIDs (`gsv proc list|spawn|send|kill`). +- **Devices** — connected machines act as execution nodes, scoped to a workspace. +- **Adapters** — Discord/Telegram workers act like device drivers for external chat. ## Development -### Prerequisites - -- [Rust](https://rustup.rs) (for CLI) -- [Node.js + npm](https://nodejs.org) (for package installation) - ```bash -# Install JS deps across the workspace, adapters, and ripgit -./scripts/setup-deps.sh - -# Start the local multi-worker development stack -npm run dev - -# CLI +./scripts/setup-deps.sh # install JS deps across workspace, adapters, ripgit +npm run dev # local multi-worker dev stack cd cli && cargo build --release +./scripts/deploy-local.sh # build + deploy local bundles (defaults to -c gateway) +``` -# Build local Cloudflare bundles and deploy via CLI -./scripts/build-cloudflare-bundles.sh -gsv deploy up --bundle-dir ./release/local --version local-dev --all --force-fetch +Requires [Rust](https://rustup.rs) and [Node.js + npm](https://nodejs.org). -# Local-bundle deploy shortcut (defaults to `-c gateway`) -./scripts/deploy-local.sh -./scripts/deploy-local.sh -c gateway --force-fetch -``` +## 🤝 Get Involved +GSV is actively evolving, and we want you to be part of the network! We welcome contributions of all sizes. +Whether you want to submit a pull request, share a wild idea, or just say hi, please don't hesitate to reach out. :) + +- **Join the Community:** Come hang out, talk shop, and share ideas on our [Discord Server](https://discord.gg/hy9ExJJFvn). +- **Found a bug or have a feature request?** [Open an issue](https://github.com/deathbyknowledge/gsv/issues). +- **Follow Updates:** Reach out directly on Twitter/X [@humachinesinc](https://x.com/humachinesinc) ## License MIT - -![gsv](https://github.com/user-attachments/assets/dba02d8f-3a3a-40c5-b38f-5eea3b2ea99d) From 0cb603102294be29664373acbd77afa4a205e7c6 Mon Sep 17 00:00:00 2001 From: kawah <119411281+ka-wah@users.noreply.github.com> Date: Thu, 25 Jun 2026 11:52:43 +0200 Subject: [PATCH 2/5] Update badge label from 'site' to 'Docs' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b2d2b6b2..fa05b81b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Release](https://img.shields.io/github/v/release/deathbyknowledge/gsv)](https://github.com/deathbyknowledge/gsv/releases) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/hy9ExJJFvn) [![X](https://img.shields.io/badge/X-@humachinesinc-000?logo=x&logoColor=white)](https://x.com/humachinesinc) -[![Docs](https://img.shields.io/badge/site-gsv.space-111)](https://gsv.space) +[![Docs](https://img.shields.io/badge/Docs-gsv.space-111)](https://gsv.space) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/deathbyknowledge/gsv) **🛸 Public beta — coming before July. Issues and PRs very welcome.** From 73499e957963c40edf53bff1114c7cbf83a31d0c Mon Sep 17 00:00:00 2001 From: kawah <119411281+ka-wah@users.noreply.github.com> Date: Thu, 25 Jun 2026 11:53:07 +0200 Subject: [PATCH 3/5] Fix badge link formatting in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fa05b81b..597eced9 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Release](https://img.shields.io/github/v/release/deathbyknowledge/gsv)](https://github.com/deathbyknowledge/gsv/releases) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/hy9ExJJFvn) [![X](https://img.shields.io/badge/X-@humachinesinc-000?logo=x&logoColor=white)](https://x.com/humachinesinc) -[![Docs](https://img.shields.io/badge/Docs-gsv.space-111)](https://gsv.space) +[![Docs](https://img.shields.io/badge/docs-gsv.space-111)](https://gsv.space) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/deathbyknowledge/gsv) **🛸 Public beta — coming before July. Issues and PRs very welcome.** From 4877e989c7303d0b4568f36dbe3efcad6ac77555 Mon Sep 17 00:00:00 2001 From: kawah <119411281+ka-wah@users.noreply.github.com> Date: Thu, 25 Jun 2026 11:57:52 +0200 Subject: [PATCH 4/5] Revise development setup commands in README Updated development instructions for building the web app. --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 597eced9..3cab4d1f 100644 --- a/README.md +++ b/README.md @@ -76,10 +76,9 @@ Linux-like by design, so agents can reason with familiar patterns (mental model, ## Development ```bash -./scripts/setup-deps.sh # install JS deps across workspace, adapters, ripgit -npm run dev # local multi-worker dev stack -cd cli && cargo build --release -./scripts/deploy-local.sh # build + deploy local bundles (defaults to -c gateway) +./scripts/setup-deps.sh # install JS deps across workspace, adapters, ripgit +cd web && npm run build # build web app +cd .. && npm run dev # local multi-worker dev stack ``` Requires [Rust](https://rustup.rs) and [Node.js + npm](https://nodejs.org). From 8c8eef9032b2fa42f2f9d40f9712d96e7b961fd7 Mon Sep 17 00:00:00 2001 From: kawah <119411281+ka-wah@users.noreply.github.com> Date: Thu, 25 Jun 2026 12:43:02 +0200 Subject: [PATCH 5/5] Update messaging platforms in README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3cab4d1f..1c587bc5 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Most personal AI agents run on one host you pick and keep alive — a laptop, a - Run things across all your machines from one agent — kick off a job on your home server while your laptop's shut. - Keep agents working while your devices sleep — they live on the edge, not your hardware. -- Reach it from anywhere — web UI, CLI, or Discord / Telegram. +- Reach it from anywhere — web UI, CLI, or Whatsapp / Discord / Telegram. - Spawn durable agents with their own memory, permissions, and the ability to start sub-agents. - Host your own packages and share apps between GSV instances through a built-in git remote. @@ -45,7 +45,7 @@ curl -sSL https://install.gsv.space | bash gsv infra deploy --api-token ``` -Open the URL it prints to finish onboarding in the Web UI. Then chat from the UI, a connected adapter (Discord/Telegram), or the CLI: +Open the URL it prints to finish onboarding in the Web UI. Then chat from the UI, a connected adapter (Discord/Telegram/Whatsapp), or the CLI: ```bash gsv chat "Hello, what can you help me with?" @@ -71,7 +71,7 @@ Linux-like by design, so agents can reason with familiar patterns (mental model, - **Kernel** — the Gateway runs on Cloudflare, exposing authenticated syscalls (`proc.*`, `pkg.*`, `sys.*`). - **Processes** — agents are durable processes with PIDs (`gsv proc list|spawn|send|kill`). - **Devices** — connected machines act as execution nodes, scoped to a workspace. -- **Adapters** — Discord/Telegram workers act like device drivers for external chat. +- **Adapters** — Discord/Telegram/Whatsapp workers act like device drivers for external chat. ## Development