Getting Started

Before you can use abyss, you’ll need a few things:

• Docker installed, with permissions to run containers
• Authentication for your agent (API keys, or whatever your LLM requires) configured in Pi.

Currently Pi is the only agent with pre-built images for you to use.

Creating Your Configuration#

The most basic, usable Pi configuration looks like this:

docker:
  # This is a pre-built image with Abyss and Pi pre-installed
  image: "ghcr.io/sethcurry/abyss-pi:latest"

  # Abyss speaks ACP, so we invoke Pi via pi-acp
  agent_command:
    - pi-acp

host_mounts:
  # This mounts the current directory inside the container.
  # It doesn't take a target path because ACP sends a `cwd`
  # so we need the paths to line up between the host and
  # container
  - source: "./"

  # This mounts your .pi directory so that the agent has
  # API keys for your LLM, prior sessions, plugins, etc.
  # 
  # You can put this in the `copy_files` config section
  # which will prevent the LLM from modifying your config files
  # but your sessions won't end up on your host PC so the session
  # files are lost when the container gets deleted.
  - source: "~/.pi"
    destination: "/root/.pi"

Paste that into a file wherever you would like. I like to store mine at the root of my code repository in a file named abyss.yaml, or in an agents directory if I have multiple configs for the repo.

You can put it anywhere you would like, though.

Connecting Your ACP Client#

In Zed, click the hamburger on the top left and click “Open Settings File”. That will pull up your Zed config file.

You need to add a section like below. If agent_servers already exists as a key, you can just append the "abyss" to the list of agents in it.

If not, put the whole section starting with "agent_servers" into the JSON blob.

{
  "agent_servers": {
    "abyss": {
      "type": "custom",
      "command": "abyss",
      "args": [
        "client",
        "-f",
        "/path/to/your/config/file/from/the/last/step.yaml",
      ]
    }
  }
}

If you would like Zed to call the agent something else, change the name of the JSON key from "abyss" to whatever you would like. (don’t change the value of the "command" key, change the "abyss" above that)

Usage#

This section is really easy: do what you were doing before. Abyss tries to stay out of your way, so there are no additional requirements or restrictions. Anything that worked before will continue to work.