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

# Daytona

> Connect Daytona cloud development environments to Serval so workflows can create and control sandboxes, snapshots, volumes, and organization settings through the Daytona API.

## About Daytona

Daytona is a cloud development environment platform for creating and managing isolated sandboxes. The Serval integration connects to Daytona Cloud or any self-hosted Daytona server using an API key, and gives your workflows full access to the Daytona API - sandbox lifecycle, in-sandbox file, git, and command operations, snapshots, volumes, and organization administration. Serval stores your API key securely and attaches it to every Daytona request your workflows make.

**Authentication:** API key (sent as a Bearer token on every request).

**Data sync:** On-demand only. Serval does not sync, ingest, or store any Daytona data in the background, and there are no triggers or inbound webhooks. All data access happens at workflow run time through requests Serval makes on your behalf.

## What the Daytona integration enables

| Capability                               | Description                                                                                                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sandbox lifecycle                        | Create, list, start, stop, resize, recover, archive, and delete sandboxes; set labels, backups, visibility, and auto-stop, auto-archive, and auto-delete intervals. |
| Files and git inside a sandbox           | List, upload, download, move, and search files, set permissions, and run git operations such as clone, commit, push, pull, and branch management.                   |
| Process execution                        | Run commands inside a sandbox, manage long-lived and terminal sessions, and fetch command logs.                                                                     |
| Computer use and language servers        | Drive a sandbox desktop (mouse, keyboard, screenshots, display info) and use language-server features such as completions and symbols.                              |
| Snapshots and volumes                    | Create, list, activate, and deactivate snapshots, fetch build logs, and manage persistent volumes.                                                                  |
| Organization administration              | Manage organizations, users, roles, invitations, quotas, usage, and suspension.                                                                                     |
| API keys, regions, and runners           | List, create, and delete API keys, and manage regions, runner infrastructure, docker registries, jobs, and object storage access.                                   |
| Preview URLs, webhooks, audit, telemetry | Generate sandbox port preview URLs (including signed URLs), manage Daytona's outbound webhook portal, read audit logs, and query sandbox telemetry.                 |

Anything defined in the [Daytona API](https://www.daytona.io/docs/en/tools/api/) can be accessed through Serval.

## Get your credentials

You need a Daytona API key. Create one in the Daytona Dashboard with the permissions your workflows will use - see the [Daytona documentation](https://www.daytona.io/docs/) for background.

<Steps>
  <Step title="Open the Keys page">
    Log in to the Daytona Dashboard and open the [Keys page](https://app.daytona.io/dashboard/keys).
  </Step>

  <Step title="Create a key">
    Click **Create Key** and enter a descriptive name, such as "Serval Integration".
  </Step>

  <Step title="Set an expiration">
    Choose an expiration date that fits your security policy.
  </Step>

  <Step title="Select permissions">
    Select the permissions your workflows will need - for example write access to sandboxes and snapshots, and read access to volumes. Health checks below also read sandboxes, organizations, and key details.
  </Step>

  <Step title="Create and copy the key">
    Click **Create** and copy the generated API key immediately.
  </Step>
</Steps>

<Warning>
  Daytona shows the API key only once, at creation. Store it in a password or secret manager before leaving the dashboard - you cannot retrieve it later, and Serval never displays the saved key again either.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Daytona connect form">
    In Serval, open the Daytona integration and start a new connection.
  </Step>

  <Step title="Instance Name (optional)">
    Optionally enter a name to distinguish between different Daytona instances (for example, "Development" or "Production"). If you leave it blank, the connection is simply named "Daytona".
  </Step>

  <Step title="Server URL">
    Enter your Daytona server URL **including the /api path** - for example [https://app.daytona.io/api](https://app.daytona.io/api) for Daytona Cloud, or your self-hosted instance URL ending in /api. The field is required - leaving it blank shows "This field is required". There is no format check beyond that, so double-check it for typos before saving.
  </Step>

  <Step title="API Key">
    Paste the API key you created in the Daytona Dashboard. This is a password field and is marked required, but the form does not actually stop you from saving with it blank - a missing or mistyped key only surfaces later as failing health checks, so double-check the paste before you save. After saving, Serval never displays the key again; the edit form shows only a masked placeholder.
  </Step>

  <Step title="Save and verify">
    Save the connection, then run the health checks below to confirm everything works.
  </Step>
</Steps>

<Warning>
  When editing an existing Daytona connection, the API Key field shows a masked placeholder - and leaving it untouched does **not** keep your existing key. Before saving any edit (even one that only changes the Instance Name or Server URL), use the replace control on the API Key field to paste the complete key, and confirm the Server URL and Instance Name are filled in exactly as desired. Saving with any field blank, or with the API Key left masked, breaks the connection.
</Warning>

## Verifying the connection

The Daytona integration ships four health checks:

| Health check                    | What it verifies                                          | On success                                                            | On failure                                                                                              |
| ------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Validate Daytona API Connection | Your API key authenticates against the configured server. | "Successfully connected to Daytona API. Authenticated as \[name]."    | "Unable to connect to Daytona API. Please verify your API key is valid and your server URL is correct." |
| List Sandboxes                  | The key can read your sandboxes.                          | "Successfully listed sandboxes. Found \[number] sandbox(es)."         | "Unable to list sandboxes. Please verify your API key has sandbox read permissions."                    |
| Verify API Key Details          | The key itself is valid and active.                       | "API key "\[name]" is valid and active."                              | "Unable to verify API key details. The API key may be invalid or expired."                              |
| List Organizations              | The key can read your organizations.                      | "Successfully listed organizations. Found \[number] organization(s)." | "Unable to list organizations. Please verify your API key has organization read permissions."           |

<Tip>
  If "Validate Daytona API Connection" passes but "List Sandboxes" or "List Organizations" fails, your key is valid but missing a scope. Create a new key in the Daytona Dashboard with the needed read permissions and update the connection, replacing the API Key with the new value and confirming every other field is filled in.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Editing the connection? Always re-enter the API key">
    Updating any field on an existing Daytona connection re-saves the whole form. The stored API key appears as a masked placeholder, and leaving it untouched does not carry the old key over - the connection ends up saved without a working key. Before saving any edit, use the replace control on the API Key field and paste the complete key, and make sure Server URL and Instance Name are filled in exactly as desired. If a connection stops working right after an edit, re-open it, re-enter all three fields, and save again.
  </Accordion>

  <Accordion title="Server URL must include the /api path">
    Serval uses the Server URL exactly as you enter it - it never adds /api for you. Use [https://app.daytona.io/api](https://app.daytona.io/api) for Daytona Cloud, or your self-hosted server address ending in /api. A URL without /api is accepted by the form and only fails later at health-check time.
  </Accordion>

  <Accordion title="No URL validation at connect time">
    The Server URL field only checks that something was entered - typos and malformed URLs pass the form and surface later as the health-check failure "Unable to connect to Daytona API. Please verify your API key is valid and your server URL is correct." If that check fails, verify the URL first.
  </Accordion>

  <Accordion title="Your API key is sent to whatever host the Server URL points at">
    To support self-hosted servers, Serval does not restrict which host the Server URL can point to. Your API key is sent as a credential to that exact address, so verify the URL carefully before saving - especially when copy-pasting it from chat messages or tickets.
  </Accordion>

  <Accordion title="Instance Name affects the connection's identity">
    Serval derives the connection's internal identity from the Instance Name (or uses a default identity named "Daytona" when blank). Renaming the instance later changes that identity, so workflows or references tied to the old name may need updating. Two Daytona connections on the same team with the same Instance Name (or both left blank) share the same internal identifier, so give each connection a distinct name.
  </Accordion>

  <Accordion title="Daytona shows the API key only once">
    Daytona displays a new key a single time at creation. If you lose it, you cannot retrieve it from Daytona or from Serval (which never displays the saved key, only a masked placeholder) - create a new key and update the connection, re-entering all fields.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Daytona integration.