Varynth

Varynth is a local coding agent in one Rust binary. It talks to a model you configure, keeps sessions on disk, and can read and edit files inside the working directory you give it.

The default screen is a full-screen terminal UI. A plain line prompt, one-shot exec, a local dashboard, and scheduled tasks are the same agent.

Install

Windows is the currently verified release platform. You need a current Rust toolchain (cargo).

Install the published package:

cargo install varynth --locked

Or build from the GitHub repository:

git clone https://github.com/ZuziaDev/varynth.git
cd varynth
cargo build --release

The binary is target\release\varynth.exe. To copy it onto your PATH:

varynth install
varynth install --startup   # also register `varynth serve` at Windows logon

install copies the executable to ~/.local/bin.

First run

varynth init
varynth doctor
varynth

init writes ~/.varynth/config.toml if it is missing. doctor checks that the selected provider has credentials and that the endpoint answers. A model call does not start until that check passes. init, doctor, sessions, and task list stay local.

Screen

varynth opens the full-screen UI. varynth --plain, or any non-terminal stdout, falls back to a line prompt.

Slash commands handled in the UI, without a model call:

/help  /commands
/goal <condition>     keep going until an independent auditor confirms the condition is met
/goal --rounds N <c>  cap the goal loop at N rounds; --minutes M caps wall time instead
/goal status          condition, round N/M, elapsed time, last auditor verdict
/goal clear           stop the current goal
/new                  archive the active session and start a fresh one
/clear                clear current context without a model call
/rename <title>       persist a session title
/context              show a component/token budget breakdown
/config               edit theme, model, permission, sandbox and keyring-backed secrets
/mcp                  inspect configured MCP servers and tools
/plugin list|search|install|remove  manage curated integrations
/effort               low, medium, high, xhigh, max, ultra
/effort <level>       set the effort directly, no menu
/permission           choose acceptEdits, prompt or bypass
/sandbox              choose read-only, workspace-write, danger-full-access or docker-isolated
/status  /skills  /models  /model
/model                pick from a select menu: arrows to move, Enter to choose, Esc to close
/model <id>           set the model directly, no menu
/compact              summarize older turns in place; also runs automatically when the session grows long
/diff                 show what changed in the working copy
/review               ask the model to review the working-copy diff
/cost                 tokens and time for this session
/doctor               same checks as `varynth doctor`
/resume [id]          open a saved session
/agents name: prompt  one background subagent, reply lands in the chat
/send <id|latest> <text>  message another session on the local bus
/inbox                read and clear messages other sessions sent to this one
/undo                 revert the last write_file/edit_file this session made
/skills-search [q]    search/install skills.sh skills without restarting
/quit  /exit

Type / and the composer lists these plus any installed skill. Arrow keys move, Tab or Enter completes, Esc closes the list.

In --plain the local commands are /status, /models, /skills, /remind <seconds> <message>, /serve, and /quit. A skill is still /name.

Commands

varynth                         full-screen UI
varynth --plain                 line prompt
varynth -C <dir>                working directory
varynth exec "fix the tests"    one shot, print the reply
varynth --mcp-config mcp.json exec "use the configured MCP tools"
varynth resume [id]
varynth sessions
varynth models
varynth doctor
varynth doctor --fix            try to start the configured local proxy
varynth install [--startup]
varynth serve [--host HOST] [--port PORT]
varynth init
varynth channels
varynth task add "name" "prompt" --at 2030-01-01T09:00:00Z
varynth task add "name" "prompt" --every-seconds 3600
varynth task list
varynth task run <id>
varynth task disable <id>
varynth task enable <id>
varynth task remove <id>

Global flags: --model, --provider, --permission-mode, --sandbox, --mcp-config.

Config

~/.varynth/config.toml. Pick one provider and put the secret in the file or in the matching environment variable. Do not commit either.

OpenAI-compatible endpoint:

model = "your-model-id"

provider = "openai"                 # openai | anthropic | proxy

openai_base_url = "https://api.example.com"   # no trailing /v1

openai_api_key = ""                 # or OPENAI_API_KEY



permission_mode = "acceptEdits"     # acceptEdits | prompt | bypass

sandbox = "workspace-write"         # read-only | workspace-write | danger-full-access | docker-isolated

effort = "xhigh"                    # low | medium | high | xhigh | max | ultra

max_tokens = 8192                   # optional: provider max output tokens

temperature = 0.2                   # optional: sampling temperature

stream = true                       # optional: set false to disable SSE streaming

theme = "purple"                   # purple | cyberpunk | dark | minimal

goal_max_rounds = 25                # optional: cap for /goal loops

goal_max_minutes = 30               # optional: wall-time cap for /goal

docker_image = "varynth-sandbox:latest"  # optional Docker image

docker_network = "none"            # none | bridge | host

use_keyring = true                  # store provider/bot/dashboard secrets in OS keyring

dashboard_host = "127.0.0.1"

dashboard_port = 7420

In prompt mode the TUI pops an allow dialog for every gated write and shell call: o once, a always for this session, d deny. A connected gateway can also answer a pending approval; the first answer wins. Non-interactive runs with no attached approver deny gated tools. Desktop control never auto-approves in acceptEdits: it requires explicit opt-in and prompt approval or bypass.

docker-isolated runs shell commands inside Docker with the workspace mounted at /work and network disabled by default. File tools still access the host workspace through the jail; configured MCP servers are external processes/services, not automatically containerized. workspace-write is a file boundary plus shell policy, not an operating-system process sandbox. Use Docker or a disposable virtual machine for untrusted commands.

Use varynth keyring set <field> to store a hidden-input secret. Supported fields are proxy-token, openai-api-key, anthropic-api-key, telegram-bot-token and dashboard-token. When use_keyring = true, these fields are omitted from saved TOML. varynth keyring status reports presence without printing values.

Values outside these lists stop startup with an error instead of silently falling back. effort maps to real provider parameters: Anthropic gets extended thinking with a budget scaled by level, OpenAI-compatible endpoints get reasoning_effort. HTTP 429/5xx provider responses are retried with backoff (Retry-After is honored).

Anthropic uses ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN. A local proxy uses proxy_url (for example http://127.0.0.1:8787) and proxy_token, or VARYNTH_PROXY_URL and VARYNTH_PROXY_TOKEN. doctor --fix starts varynth-proxy from PATH when the configured proxy_url is a loopback address. It does not download one.

Other environment overrides: VARYNTH_MODEL, VARYNTH_PROVIDER, VARYNTH_DASHBOARD_TOKEN, VARYNTH_MCP_CONFIG.

permission_mode controls writes. sandbox controls how far shell and file tools may reach. workspace-write is the default and stays inside the working directory.

MCP

--mcp-config <file> loads one JSON file for that command. VARYNTH_MCP_CONFIG loads it for every command. HTTP, streamable HTTP, and stdio (spawned local server) endpoints are supported. Tools from these servers still pass through the permission mode and the sandbox.

{
  "mcpServers": {
    "local-tools": {
      "type": "http",
      "url": "http://127.0.0.1:9000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/some/dir"]
    }
  }
}

A server entry with a command and no type is treated as stdio. Stdio children are spawned on first use, killed on exit, and restarted automatically if they die.

Model replies stream token by token (SSE) into the TUI and the dashboard when the provider supports it; set stream = false to turn that off.

Sessions, skills, tasks

Sessions are stored under ~/.varynth. resume without an id opens the latest one.

Project instructions are read from VARYNTH.md, AGENTS.md, or CLAUDE.md in the working directory. Skills are a SKILL.md under .varynth/skills, .claude/skills, or ~/.varynth/skills, and are called with /name.

Agent files (SOUL.md, USER.md, MEMORY.md, DREAM.md, HEART.md) are created in ~/.varynth and in <project>/.varynth only when missing. Project files layer over the global ones and are passed to the model as untrusted context. Memory appends stay inside the project MEMORY.md.

Tasks live in ~/.varynth/tasks.json. --at takes an RFC3339 timestamp. --every-seconds repeats. varynth serve checks for due tasks every 15 seconds. Each run opens a session and calls the configured model. Background runs cannot use the shell or write files unless that task was created with --allow-background-tools.

Built-in tools: read_file, write_file, edit_file, glob_search, grep_search, bash, web_fetch (http and https only; loopback, private, link-local, and cloud-metadata addresses are blocked, including across redirects), memory_read, memory_append, session_send, and session_inbox.

Goals and session-to-session mail

/goal <condition> turns the agent into a supervised loop. After every turn an independent auditor model call judges the transcript against the condition and answers {"met": bool, "reason": str}; the loop continues on a negative verdict and stops the moment the auditor confirms the objective (a model GOAL_COMPLETE claim alone is not enough). --rounds N / --minutes M or goal_max_rounds / goal_max_minutes cap the loop; the header shows goal N/M.

Sessions talk over a local bus at ~/.varynth/bus.jsonl (lock-protected, pruned after a day). The session_send and session_inbox tools let a running agent exchange mail with other sessions; /send <id|latest> <text> and /inbox do the same from the keyboard. Mail waiting for a session is injected into its next turn automatically. The dashboard can post mail too: POST /api/session/{id}/messages with {"text": "..."}, and session listings carry an unread count.

Every write_file and edit_file first checkpoints the file's previous content under ~/.varynth/checkpoints (per session, last 100, files over 2 MB are skipped). /undo reverts the most recent write — repeat it to walk backwards.

Dashboard and Telegram

varynth serve

Open http://127.0.0.1:7420. The deck lists sessions, lets you pick a model, and streams a chat against this machine. Requests with a foreign Host header are rejected, and the API is same-origin only. If you bind a non-loopback host, set VARYNTH_DASHBOARD_TOKEN. /api/* then requires Authorization: Bearer <token> (compared in constant time).

Telegram needs its own bot token from BotFather, not a token shared with another app. Put it in ~/.varynth/telegram.env as TELEGRAM_BOT_TOKEN=..., or set VARYNTH_TELEGRAM_BOT_TOKEN, then run varynth serve. The first direct message tells you your numeric user id. Add that id to telegram_allow_from and restart serve.

telegram_allow_from = ["123456789"]

Discord and WhatsApp adapters are not in this binary.

Computer Use

Desktop tools are opt-in: set VARYNTH_COMPUTER_USE=1 in the Varynth process environment, then use prompt for interactive decisions or explicitly select bypass. They provide screenshot capture with a coordinate grid, mouse click/drag, keyboard text/key combinations and Windows window list/focus/resize. computer_stop remains available without opt-in. The emergency stop is the pointer corner (0,0) or Esc / Ctrl+Alt+Q. Docker mode denies desktop access; read-only mode denies desktop input. Screenshots are written under the workspace jail, not arbitrary paths.

The implementation's parsers, jail checks and failsafe paths are covered by offline tests. Live desktop interactions are not run by the project test suite.

Gateway

The dashboard exposes /ws/gateway with JSON-RPC 2.0 methods: ping, status.get, sessions.list, session.get, session.message, session.pause, session.resume, session.context, models.list, model.set, and approval.respond. Browser connections pass the dashboard token as ?token=...; non-browser clients may use a Bearer header. Foreign Origin requests are rejected as well as invalid Host headers.

Terminal events are forwarded across local processes through ~/.varynth/control. session.pause stops at the next model/command boundary, session.resume continues, and session.context queues a bounded text-only context replacement for the next turn. Remote approval ids can also be answered by an allowlisted Telegram user with approve <id> once|always|deny. The /diff page renders pasted unified diffs side by side.

Node.js

bindings/node is an ESM package. VarynthClient calls the CLI. AgentWorkspace reads the layered agent files. Set VARYNTH_BINARY when the executable is not inside the repository.

cd bindings\node
npm install
npm run build