Vis

Getting started

Use Vis to explore a project, change code and run checks. Start in your terminal, or connect the desktop or phone app.

Install

Install Vis where your work runs

Install Vis on the computer with your project. Native packages support Apple silicon macOS and Linux (x64 or ARM64). On Windows, use Linux in WSL2. For other platforms or source builds, see Runtime distributions.

The installer needs curl and tar, but not Java or Git. It writes to ~/.local/bin and can update your shell profile. Read the installer before running it:

curl -fsSL https://github.com/Blockether/vis/releases/download/installer/install-vis-agent | bash

The desktop and phone apps connect to this engine. They do not run it themselves. For a Python program, pip install vis-agent is enough: the Python SDK downloads Vis on first use.

Get the desktop app

Use the buttons below to download Vis for Windows x64, universal macOS, or Linux x64. For Linux ARM64, download the AppImage. You can also browse all packages on the latest GitHub release.

Download Vis for Windows x64 Download Vis for macOS Download Vis for Linux x64

Install the package, open Vis, then follow the connection steps below. See Desktop setup for installation and launcher options.

iPhone, iPad and Android

These apps are public betas. After installing one, connect it.

TestFlight for iOS and iPadOS Google Play beta for Android

First session

Choose a provider and model before sending a task. A provider may need an account or API key and may charge for use. You can also use Ollama or LM Studio for a local model. See Providers and models.

Vis can edit files and run commands. Start with a read-only task while you get familiar with it.

In the terminal

Open a terminal in your project:

cd /path/to/project
vis-agent tui

Vis starts a local gateway if needed.

  1. Add a provider in the provider picker.
  2. Follow its sign-in instructions.
  3. Select a model.

Press Enter to send a message. See Keyboard shortcuts for new lines and other keys.

In the desktop or phone app

Connect the app, then open your project and start a session. Choose a provider and model there.

Try a first task

Explain how this project is organized and where its tests live. Don't change any files.

The answer should describe your project's structure and tests. Open Activities to see the searches and files Vis read.

Next, ask for a small change and the tests for it. Review the diff before using the changes. To limit what Vis can access, see Process jail and network policy.

Connect an app

The desktop and phone apps connect to a gateway, the Vis service on the computer with your project. Your files and commands stay on that computer. You can use the same sessions as in the terminal.

Install Vis there first. You do not need a separate Vis account to connect an app.

Connect the desktop app

On macOS and Linux, open the app from a terminal:

vis-agent desktop

This command opens the app. If no local gateway runs, it starts one in the background. The gateway stays up while the app runs.

  1. In Add a machine, enter http://127.0.0.1:7890.
  2. Leave the bearer token empty for the default local gateway.

You add the machine only once.

If you open the app another way, no gateway starts. Check for a running gateway:

vis-agent gateway status

If none is running, start one:

vis-agent gateway start --host 127.0.0.1

Keep that terminal open. This command runs the gateway in the foreground.

If you enabled token authentication, enter its token. If you reused a running gateway, use the address shown by vis-agent gateway status.

The app can reach a local WSL2 gateway through localhost forwarding. On an Intel Mac, use the JVM distribution or a gateway on another computer.

For a gateway on another computer, pair the app and paste the pairing link. 127.0.0.1 only reaches the device you are using.

Pair a phone

Your phone needs an address it can reach over your local network or a private VPN. A gateway on 127.0.0.1 is not reachable from your phone.

Keep token authentication enabled for remote access. Pairing links and QR codes include the token. Treat them like passwords and do not share them publicly. Use a trusted network, VPN or HTTPS for remote connections.

On the computer running Vis, replace 10.0.0.5 with its network address:

vis-agent gateway start --host 10.0.0.5 --require-token --pair

Keep that terminal open. In Add a machine, scan the QR code or paste the pairing link. You can now open projects and sessions from that computer.

If a gateway is already running, create a pairing link without restarting it:

vis-agent gateway pair

If it listens only on 127.0.0.1, you need to restart it with a reachable address. Check for active work before stopping it. See Stop or restart a gateway.

For access away from home or custom pairing addresses, see Remote connections.

See Vis in action

The terminal images show an earlier header with session tabs. Current builds show only the active session title. Use Projects to browse saved sessions.

Gateway reference

For remote connections, tokens and service setup, see Running a gateway. To use Vis from your own code, see Python SDK basics or HTTP API basics.

Learn more

Intro

Concepts

Each concept page explains one feature: what it does, when to use it and how to start.

  • Sessions — continue, stop or find your work.
  • Context management — how filtering and summaries keep conversations manageable.
  • Project instructions — tell the agent how your codebase works.
  • Skills — reusable task instructions.
  • Drafts — review changes in a separate working copy.
  • Council — ask another session for help or a second review.
  • Automations — run a prompt on a schedule or from a webhook.
  • Siri and Shortcuts — talk to Vis with the Action Button and use answers in shortcuts.
  • Evaluations — score benchmark rounds, find failure causes and compare runs.
  • Forms and user input — ask for choices, credentials or confirmation.
  • Live views — show progress a person can watch and stop.
  • Speech and voices — speak text, transcribe recordings and add your own voices.
  • Python sandbox — Python execution, packages and permissions.
  • Configuration — providers, models and project settings.
  • Decision models — download Laya, train and publish FP32 versions.

Programmatic access

Use these pages to drive the same features from your own code. Start with the basics page for Python or for HTTP. Then read the API page for the feature. Each API page shows the Python examples. To see the same steps as HTTP requests, select HTTP at the top of the page.

Basics

  • Python SDK basics — install the SDK, run a private agent and connect to a gateway.
  • HTTP API basics — authenticate requests, read the OpenAPI document and handle errors.
  • Extension API — declarations, tool contracts and host operations for extensions.

Feature APIs

  • Sessions API — sessions, messages, progress and saved work from Python or HTTP.
  • Context management API — context budget, usage and cache health from Python or HTTP.
  • Project instructions API — prompt templates, skills and goals from Python or HTTP.
  • Drafts API — draft settings and draft state from Python or HTTP.
  • Council API — Council messages, wakes and rooms from Python or HTTP.
  • Automations API — automations, runs, secrets and webhooks from Python or HTTP.
  • Evaluations API — benchmark scores, failure causes and comparisons from Python or HTTP.
  • Speech API — speech, transcription and your own voices from Python or HTTP.
  • Configuration API — settings and extension reloads from Python or HTTP.

Extensions

Reference

BlocketherEdit on GitHub ↗