# @vess-id/vess

> Local AI agent runtime — manages identity, permissions, and execution boundaries for AI coding agents.

## What is VESS?

VESS is a local runtime that gives your AI coding agent a cryptographic identity and enforces security boundaries on your machine.

- **Creates a DID-based cryptographic identity** for your development machine, stored securely in the OS Keychain
- **Registers as an MCP (Model Context Protocol) server** in Claude Code, so the agent operates within VESS-managed boundaries
- **Manages environment variable secrets** via OS Keychain with Touch ID protection — secrets never sit in plaintext on disk
- **Connects to the VESS gateway** for project management and credential issuance

## Beta Status

This is a **beta release** (v0.1.0).

| Platform | Status |
|----------|--------|
| **macOS + Claude Code** | Primary target, fully supported |
| **Linux** | Daemon/service support exists but not fully tested |
| **Windows** | Not supported |

## Prerequisites

- **Node.js 22** or later
- **macOS** (primary) or Linux
- **Claude Code** — [installation guide](https://docs.anthropic.com/en/docs/claude-code)
- **A VESS account** — sign up at [app.vesslabs.ai](https://app.vesslabs.ai)

## Getting Started

### Step 1: Sign Up

1. Create an account at [https://app.vesslabs.ai](https://app.vesslabs.ai)
2. Create a project
3. (Optional) Connect integrations: Slack, Google Calendar, Jira

### Step 2: Install & Initialize

```bash
npm install -g @vess-id/vess
vess init
```

This single command will:

- Generate a cryptographic identity (DID) for your device
- Open a browser for device verification
- Install a background daemon (auto-starts on login, localhost only)
- Register VESS as an MCP server in Claude Code

### Step 3: Verify

Restart Claude Code, then:

```bash
vess status
```

## Commands

### Core

| Command | Description |
|---------|-------------|
| `vess init` | Initialize device + daemon + MCP registration (all-in-one) |
| `vess init --no-daemon` | Initialize without daemon (stdio mode only) |
| `vess init --no-install` | Initialize without Claude Code MCP registration |
| `vess init --force` | Force re-initialization even if already set up |
| `vess login` | Re-authenticate after session expiry |
| `vess status` | Show runtime status (auth, daemon, wallet) |
| `vess doctor` | Diagnose setup issues |
| `vess uninstall` | Completely remove VESS (MCP, daemon, config, keychain) |

### MCP Registration

| Command | Description |
|---------|-------------|
| `vess mcp register` | Register VESS as an MCP server in Claude Code |

> Tip: `vess init` runs this automatically. Use `vess mcp register` only if you skipped MCP registration during init or need to re-register after manual removal.

### Daemon

| Command | Description |
|---------|-------------|
| `vess daemon start` | Start the daemon (default: `127.0.0.1:3100`) |
| `vess daemon start --foreground` | Run in foreground (no daemonization) |
| `vess daemon stop` | Stop the running daemon |
| `vess daemon enable` | Enable auto-start on login (installs OS service) |
| `vess daemon disable` | Disable auto-start (removes OS service) |

### Logs

| Command | Description |
|---------|-------------|
| `vess logs` | Show recent daemon output (default: 50 lines) |
| `vess logs --follow` | Stream logs in real-time |
| `vess logs --lines 100` | Show last 100 lines |

### Projects

| Command | Description |
|---------|-------------|
| `vess project list` | List available projects |
| `vess project use <id>` | Switch active project |
| `vess project sync` | Re-fetch projects from gateway |

### Environment Secrets

| Command | Description |
|---------|-------------|
| `vess env import <file> --profile <name>` | Import .env into a secure profile |
| `vess env list` | List profiles and stored keys |
| `vess env list --profile <name>` | Show keys for a specific profile |
| `vess env delete --profile <name>` | Remove secrets from keychain |
| `vess env delete --profile <name> --keys <k1,k2>` | Remove specific keys only |
| `vess env restore --profile <name>` | Decrypt and restore .env (requires Touch ID) |
| `vess env restore --profile <name> --output <path>` | Write restored .env to a file |
| `vess run -- <command>` | Run command with decrypted env injection |

**`env import` options:**

| Flag | Description |
|------|-------------|
| `--interactive` | Classify each variable interactively |
| `--all-secret` | Treat all variables as secrets |
| `--keys <k1,k2>` | Specify which keys are secrets (rest are plaintext) |
| `--plaintext-keys <k1,k2>` | Specify additional plaintext keys (used with default mode) |
| `--dry-run` | Preview classification without making changes |
| `--skip-integration` | Skip post-import integration steps (package.json, CLAUDE.md, hooks) |

> Note: `--interactive`, `--all-secret`, and `--keys` are mutually exclusive.

**`run` options:**

| Flag | Description |
|------|-------------|
| `--profile <name>` | Env profile name (for logging) |
| `--cwd <dir>` | Working directory |
| `--timeout <seconds>` | Timeout in seconds |

## What Works in Beta

- Device identity creation (DID key pair, OS Keychain storage)
- Device enrollment via browser-based verification
- MCP server registration in Claude Code (stdio + HTTP daemon)
- Environment variable management with OS Keychain-backed secrets
- Touch ID-gated secret access (macOS)
- Project management (list, switch, sync)
- Audit logging
- OS service integration (launchd on macOS, systemd on Linux)

## Known Limitations

- Web dashboard signup and project creation required before CLI use
- No team/org-level policy sharing yet
- No automatic credential rotation
- Session tokens expire — run `vess login` to re-authenticate
- `vess env import --interactive` mode is experimental
- Daemon auto-start is set up during `vess init`; run `vess daemon enable` to re-enable if disabled

## How It Works

```
┌─────────────┐     MCP Protocol     ┌──────────────┐
│ Claude Code  │ <──────────────────> │  VESS agentd │
└─────────────┘    (stdio or HTTP)    └──────┬───────┘
                                             │
                                    ┌────────┼────────┐
                                    │        │        │
                               ┌────▼──┐ ┌──▼───┐ ┌──▼────┐
                               │Policy │ │Wallet│ │Keychain│
                               │Engine │ │ (DB) │ │ (OS)  │
                               └───────┘ └──┬───┘ └───────┘
                                            │
                                     ┌──────▼──────┐
                                     │VESS Gateway │
                                     │(api.vess.id)│
                                     └─────────────┘
```

## Data Storage

All data stored under `~/.vess/`:

| File | Purpose |
|------|---------|
| `config.json` | Gateway URL, root DID, default project |
| `policy.json` | Local deny rules |
| `wallet.db` | SQLite — credentials, projects, audit logs |
| `logs/` | Audit log directory |

Secrets (root key, session token, env values) are stored in the **OS Keychain**, not on disk.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Not initialized" | Run `vess init` |
| "No projects found" | Create one at [app.vesslabs.ai/projects](https://app.vesslabs.ai/projects), then `vess project sync` |
| Session expired | Run `vess login` |
| Claude Code doesn't see VESS | Run `vess mcp register`, restart Claude Code |
| Daemon not starting | Check `vess logs`, try `vess daemon start --foreground` |
| Need a fresh start | Run `vess uninstall`, then `vess init` |
| Diagnose issues | Run `vess doctor` |

## Support

For bug reports, feature requests, or questions, please contact us at info@vess.id

## License

Business Source License 1.1 — see [LICENSE](./LICENSE) for details.