> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub.agentsea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

`SurfKit` is an orchestartor for building and launching agents locally, in a docker container,
or in the cloud. Think of it as k8s for agents.

There are several key concepts `SurfKit` operates with:

* **Device** is a medium by which an agent interacts with the world. It defines a set of observations and actions available to the agent in
  solving a task. We currently only support one kind of device which is a [Desktop](https://github.com/agentsea/devicebay) VM, that can run locally (via Docker or QEMU), in GCP or in AWS.
  We plan to implement more types of devices soon, or you can create one by implementing the [DeviceBay](https://github.com/agentsea/devicebay) protocol.
* **Tracker** is an entity that takes care of assigning and observing the tasks among the agents. Trackers are run in Docker or in K8s.
* **Type** is the type of the Agent, for example, [SurfPizza](https://github.com/agentsea/surfpizza), [SurfSlicer](https://github.com/agentsea/surfslicer),
  or [SurfMonsta](https://github.com/agentsea/surfmonsta). The types can be defined either in the Agentsea Hub
  (more on that later), or in the local repository.
* **Agent** is an entity of one of the types. That's the process that is going to solve the tasks for you, that can be executed as
  a local process (which is super handy during development), in a Docker container or in K8s.
* **Task** is a unit of an Agent operation that has a description and a device to execute that action against. A task may be as simple as
  *"Find me an image of a cool cat on Google"* or as complex as looking for accomodation on Airbnb with lots of filters and search aspects.

The `Hub` is a place where you can publish and find the agents. It's in early alpha right now, and we have a lot of deveploment planned for it.

The typical usage of an agent is as follows:

* You pick an agent **type** from Hub or by cloning a repo.
* You create a **device** if the agent needs it.
* You create a task **tracker** (optionally, because it will be created if absent).
* You create an **agent** of a given type.
* You ask it to solve the **task**.
* ...
* Profit!

If you want to give it a try as quickly as possible, go to [Quickstart](../quickstart). On this page, we'll dive a bit deeper. So let's go!

If you could only use agents we've developed, that wouldn't be all that useful. `SurfKit` allows you to create and
publish your agents in Hub, so that other people can find and re-use them. See [Building Your Agent](../advanced_tutorial) for details.

## CLI basics

You can see the detailed (yet incomplete) list of CLI commands at [CLI Documentation](./cli). To see a complete list of commands do this:

```sh theme={null}
surfkit --help
```

The goal of this section is to tell you more about the lifecycle of each entity we listed above.

* **Devices**, **Trackers**, and **Agents** are similar: you can `create` any of them, `list` them,
  `get` information about them (except for trackers), read the `logs` for agents and trackers and `view` the devices,
  and `delete` any of them to remove the corresponding entity and free up resources.

```sh theme={null}
surfkit create agent
surfkit list agents
surfkit get agent -n foo
surfkit delete agent -n foo
```

* **Tasks** are created via `solve` and you can stop them in UI or by cancelling the process with ctrl+c. You can
  `list` them and `get` information about them while they are in progress.

* **Types** are the most unique entities in this list:

  * To create a repository for a new type of agent, you run `new`.
  * Every time you run an agent from the repo, it gets registered in your local database, so you'll see it via `find`.
  * To build an image for the agent type, you run `build`.
  * When the image is uploaded and the `agent.yaml` is updated, you can `login` into Hub and `publish` this type. Now other users will be able to use it!