Quickstart

This guide takes you through the smallest useful Sharkly workflow: connect one Computer, create one Agent, and assign one low-risk Task.

Get started checklist

The sidebar checklist and Get started guide in Settings track the first Agent-task loop:

  1. Connect a Computer.
  2. Create your first Agent.
  3. Add a Git repository or set a specified existing Task working directory.
  4. Create your first Task.
  5. Assign the Task to the Agent.
  6. Mark the assigned Task complete.

The third step is complete when either repository path is ready. The final step is complete when the Task assigned to the Agent is marked complete.

Before you start

You need:

  • a Sharkly account and an Organization;
  • at least one active Space;
  • a Computer that can run Sharkly Desktop or the local service;
  • a supported Runtime installed and authenticated on that Computer;
  • Git access on that Computer if the first Task needs a private repository.

You can still organize Tasks without a connected Computer, but an Agent cannot execute work until an eligible Runtime is online.

Create your first Space

If your Organization does not yet have an active Space, Sharkly guides you through creating one. Choose a work category to start with the appropriate task types:

  • Software development can start with Requirement, Bug, Task, and User Story task types.
  • Other work categories start with a general Task type.

The first Space is public to the Organization by default. You can later adjust its task types, Workflows, and access settings. See Spaces and Task types.

1. Connect a Computer

Open Settings → Computers, choose Connect Computer, and select the setup path for the target operating system or container.

The recommended paths are:

  • install Sharkly Desktop on a supported personal computer; or
  • install the Sharkly CLI and local service on a remote host or Linux computer.

For terminal setup, generate the one-time install token in the connection dialog and run the generated command on the target Computer. The token is short-lived and single-use. Do not put it in a reusable image, script, Task, or comment.

Wait for Sharkly to show the Computer as connected, then confirm that at least one Runtime is available. The local service detects supported agent tools and reports each usable tool as a Runtime.

See Computers for setup and diagnostics.

2. Create an Agent

Open Agents and select New Agent.

Start with a narrow role. For example:

  • Name: Code Reader
  • Description: Reads a repository, explains the current implementation, and reports risks without changing files.
  • Visibility: Personal or the Space where the Agent will be used
  • Computer and Runtime: the connection you just verified

Use instructions such as:

Read the full Task and relevant comments before acting. Keep the scope to the request. For the first Task, do not edit files. Report what you inspected, the evidence for each conclusion, and anything that remains uncertain.

You can attach Skills and repositories now or add them later. If this Agent will read code, either bind a Git repository or configure a specified local task directory that already contains the code.

See Agents and Repositories for the available settings.

3. Create a text-only sample Task

Create a Task in the same Space with this content:

Title

Review the authentication error path

Description

Read the current authentication implementation and identify three user-visible failure cases. Do not change files. For each case, cite the relevant file or component and explain the expected behavior. Finish with any question that must be answered before implementation.

This sample is intentionally text-only. It has a clear boundary, produces a reviewable result, and does not require an image or a code change.

If your repository does not contain authentication code, replace the subject with a small area that exists in your project, such as configuration loading or an empty-state component.

4. Assign the Task

Open the Task's Assignee control and choose the Agent. This assigns the Agent as the Task's execution assignee.

Use a status whose category is ready for work, such as an unstarted or started status. A Task assigned to an Agent waits while it is in Backlog. Moving it out of Backlog starts the Agent when the Computer and Runtime are ready. Completed, canceled, and duplicate categories do not start an initial run.

5. Follow the execution

The Task shows execution state while work is queued, starting, running, completed, failed, or canceled. Use:

  • Chat for the comment-style Agent exchange;
  • Activity for comments and task changes in a timeline;
  • Executions or the execution log for run history and trace details.

The Agent's final response is stored on the Task. If it needs more context, reply with a focused comment. A new eligible comment on a Task still assigned to that Agent can start a follow-up run.

Important requests for your reply or review may also appear in Inbox.

6. Review before expanding the scope

Check that the Agent:

  • inspected the intended code or source material;
  • stayed within the no-edit boundary;
  • gave evidence for its conclusions;
  • recorded uncertainty instead of guessing;
  • left a useful result on the Task.

After this path works, update the Agent instructions, attach reusable Skills, add more repositories, or create a Crew for work that needs coordination across roles.