docs/generated/getting-started.mdgenerated from code

Start · 5 min read

Getting started

Install agentflare, make a project, and join it from another machine.

On this page
1. Install2. Start a project3. Watch it in your browser4. Open an issue5. Add an AI agentNextDetails: installing, other machines, and access

Five steps, about five minutes, from nothing to a project you watch change live in your browser.

1. Install

On Linux or macOS:

terminalon main
1curl -fsSL https://sh.lvcs.sh | sh

On Windows, in PowerShell: irm https://ps.lvcs.sh | iex.

This puts agentflare in ~/.local/bin and runs it in the background for your user, updating itself to signed releases (agentflare update --auto off stops the updates). If the installer says ~/.local/bin is not on your PATH, add it as it says, or open a new terminal, before the next step.

2. Start a project

In any folder of code:

terminalon main
1cd ~/code/my-project2agentflare init

The folder's files are now the project's first version. There is no commit step: from here on every save you make lands as you make it, and each file keeps its history. af doesn't use git, and a .git folder in the project is left alone: if the folder is already a git repository, keep committing and pushing as you did.

3. Watch it in your browser

terminalon main
1agentflare auth login

Open the link it prints and check that the code in the browser matches the one in the terminal. Now edit any file in your editor and save it: the change shows up in the browser's Code tab as you save.

4. Open an issue

terminalon main
1agentflare issue new "Try af" --body "My first issue"

It shows in the browser's Issues tab, where anyone you let in can reply.

5. Add an AI agent

terminalon main
1agentflare key new --alias agent-1

This prints the agent's own id. Start your coding agent in the project folder with LVCS_PEER set to that id, and its edits land beside yours, under its own name, live. With Claude Code or OpenCode, the af plugin does this for every session: see the Agent guide.

Next

  • agentflare status shows where you stand and your next step, any time.
  • To work with someone on another machine, they run agentflare join <project-id> and you give them access: see Details, below.
  • The words af uses on screen are explained in Words af uses.

Details: installing, other machines, and access

On Linux or macOS (x86_64 or arm64):

terminalon main
1curl -fsSL https://sh.lvcs.sh | sh

On Windows, in PowerShell:

powershellon main
1irm https://ps.lvcs.sh | iex

The installer puts agentflare in ~/.local/bin (LVCS_INSTALL_DIR moves it) after checking it against the release's Ed25519-signed manifest, then runs agentflare install, which starts your one per-user daemon as a service. agentflare uninstall removes the service and leaves your projects alone. agentflare update moves to the latest signed release.

On Linux, agentflare install also turns on lingering (loginctl enable-linger) so the daemon keeps running after you log out of SSH; where it can't, it prints the sudo command to run once. Where there is no service manager (a container, WSL without systemd), the installer says so, skips the service, and you run the daemon yourself:

terminalon main
1nohup ~/.local/bin/agentflare daemon > ~/agentflare-daemon.log 2>&1 &

To build from source instead (Rust toolchain pinned in rust-toolchain.toml): cargo build --release -p lvcs, then run agentflare install with that binary.

Start a project in any directory. Its current files become the first version. The directory can already be a git repository: af leaves .git alone, so you keep committing and pushing as before:

terminalon main
1cd ~/code/my-project2agentflare init3# prints: agentflare init owner=<peer> project=<project-id> node=<node id>

On another machine on the same network, join it. The two nodes find each other on the local network (mDNS):

terminalon main
1agentflare join <project-id> --root ~/code/my-project2# prints: agentflare join peer=<peer> project=<project-id> node=<node id>

From another network, one of the two machines needs an address the other can dial (an open port, a VPN, or a public host), or a relay both can reach: this release names no public relay, so agentflare status says relay: off until LVCS_RELAY in the daemon's environment names one (agentflare daemon --relay on a host with a public address serves as one, on TCP 4402 and UDP 4401). Behind a relay, the owner's node reserves a circuit on it, and the two nodes connect directly when hole punching works, else through the relay. Run agentflare status in the project on the owner's machine; its address lines are the addresses a joiner dials, relayed ones first. Name one when you join:

terminalon main
1# on the owner's machine, in the project2agentflare status3# address /ip4/<relay>/tcp/4402/p2p/<relay id>/p2p-circuit/p2p/<node id>4# on the joining machine5agentflare join <project-id> --root ~/code/my-project --bootstrap <one of those addresses>

A relay carries only encrypted traffic and never learns the project. LVCS_RELAY=off in the daemon's environment turns relays off, and agentflare status then says relay: off.

A join with no grant completes after it verifies the project's capabilities. It prints the new peer= but receives no private files yet. agentflare status on the joined machine says it is waiting and names the grant command for the owner. To let that peer read, run this on the owner's machine:

terminalon main
1agentflare grant <peer> read2# prints: {"grant":"<grant id>",...}; agentflare revoke <grant id> takes it back

Or grant write instead to let it edit. A grant starts file sync automatically, with no restart. A grant's paths limit what that peer can read and write through af, but its node still holds every file: to keep a file from someone, don't grant them a place in this project.

To see a project in your browser, run agentflare auth login in it, open the link it prints, and confirm the code matches the terminal's. The browser reaches your daemon directly over WebRTC where it can, and through the relay where a NAT or firewall blocks every direct path, so the link works from any network.

Other useful commands:

  • agentflare status shows where you stand: grants, unread notifications, stale saves, nodes, and the last error with its next step.
  • agentflare key new --alias <name> creates an agent with its own key and grant. It edits the project root like everyone else, as LVCS_PEER=<id>.
  • agentflare explain <value> explains any error code, rule, or path, offline.
  • agentflare audit checks every stored change's signature and grant.
  • agentflare replay --check replays the journal.

Agents and permissions: an agent has the permissions of the node it runs on, with or without a plugin. Plugins add per-agent names and early warnings, but they aren't a security boundary. To limit an agent, give it its own node in a VM or container: run agentflare join there, then agentflare grant it what it needs on the owner's machine.