Fly Sprites

https://docs.fly.io/sprites
Admin
Fly Sprites provides persistent, hardware-isolated Linux microVMs for running arbitrary code, AI...
Tokens:143,905
Snippets:1,022
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### sprite auth setup example

Source: https://docs.fly.io/sprites/cli/commands

Example of the sprite auth setup command with a token in the required format.

```bash
sprite auth setup --token "org-slug/org-id/token-id/token-value"

```

--------------------------------

### Create checkpoint and install ripgrep

Source: https://docs.fly.io/sprites/integrations/remote-mcp

Example request that creates a checkpoint on mcp-demo, installs ripgrep, and verifies rg --version.

```text
Create a checkpoint on mcp-demo before making changes. Then install ripgrep and verify rg --version.
```

--------------------------------

### Get Service Logs with Go

Source: https://docs.fly.io/sprites/api/services/get-service-logs

Go example using the net/http package to fetch service logs. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Response: Start Service

Source: https://docs.fly.io/sprites/api/services/start-service

Example 200 response showing log entries with timestamps and types, including stdout and complete events.

```json
[
  {
    "timestamp": 1735988400000,
    "type": "started"
  },
  {
    "data": "Starting server...\n",
    "timestamp": 1735988400000,
    "type": "stdout"
  },
  {
    "data": "Listening on port 8000\n",
    "timestamp": 1735988401000,
    "type": "stdout"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988402000,
    "type": "complete"
  }
]
```

--------------------------------

### Install and start DeepSeek Harness Sprites bundle

Source: https://docs.fly.io/sprites/integrations/agent-plugins

Installs the Sprites bundle into the built-in Web profile and starts that profile. Requires Node.js 20.19 or newer and the DeepSeek Harness developer preview. Complete browser OAuth on the first connection; if the initial tool synchronization times out, finish the browser flow and restart Harness once.

```bash
npx @deepseek-ai/dsh plugin --profile web add github:superfly/sprites-deepseek-plugin
npx @deepseek-ai/dsh --profile web

```

--------------------------------

### sprite use examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of activating a sprite for the current directory.

```bash
sprite use my-sprite
sprite use -o myorg dev-sprite
sprite use
```

--------------------------------

### Go example using net/http

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses Go's net/http package to send a GET request to the read-file endpoint. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/fs/read"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### spawn: Create Sprite, install SDK, and start runner service

Source: https://docs.fly.io/sprites/integrations/claude-managed-agents

The spawn function creates a Sprite with the given name, waits for capacity, writes the runner script and environment file, installs the Anthropic SDK, and starts the agent-runner service. It tolerates an existing Sprite (409) and throws an error if the SDK install fails. The environment key is written to a file to avoid appearing in process listings.

```typescript
export interface SpawnParams {
  environmentId: string;
  workId: string;
  environmentKey: string;
}

export async function spawn(sessionId: string, opts: SpawnParams): Promise<string> {
  const name = spriteName(sessionId);
  const bytes = (s: string) => new TextEncoder().encode(s);

  // Tolerate the Sprite already existing (reuse it): 200/201 created, 409 exists.
  const created = await api('POST', '/v1/sprites', {
    body: JSON.stringify({ name, wait_for_capacity: true }),
    headers: { 'content-type': 'application/json' },
  }, 300_000);
  if (![200, 201, 409].includes(created.status)) {
    await ok(created, 'POST /v1/sprites');
  }
  await fsWrite(name, RUNNER_PATH, bytes(RUNNER_SRC));

  // Install the SDK and create the workspace. This runs on every new Sprite; the
  // checkpoint note at the end of the guide covers cutting the cost. A nonzero
  // exit means the install failed (e.g. PyPI is blocked).
  const code = await exec(name, 'mkdir -p /workspace && python3 -m pip install -q anthropic');
  if (code !== 0) throw new Error(`sprite ${name}: runner setup failed (exit ${code})`);

  // The env contract Anthropic's worker reads. The environment key is the
  // runner's only credential. Written to a file (not service args) so it never
  // appears in process listings; the service deletes it right after sourcing.
  const env: Record<string, string> = {
    ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL ?? 'https://api.anthropic.com',
    ANTHROPIC_ENVIRONMENT_KEY: opts.environmentKey,
    ANTHROPIC_SESSION_ID: sessionId,
    ANTHROPIC_ENVIRONMENT_ID: opts.environmentId,
    ANTHROPIC_WORK_ID: opts.workId,
  };
  const envFile = Object.entries(env).map(([k, v]) => `${k}=${shquote(v)}`).join('\n') + '\n';
  await fsWrite(name, '/root/runner.env', bytes(envFile));

  const svcPath = `/v1/sprites/${name}/services/agent-runner`;
  const svc = await api('PUT', svcPath, {
    body: JSON.stringify({ cmd: 'bash', args: ['-lc', SERVICE_CMD], needs: [] }),
    headers: { 'content-type': 'application/json' },
  });
  await ok(svc, `PUT ${svcPath}`);
  return name;
}
```

--------------------------------

### Get a sprite with Go

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

Go example using net/http to fetch a sprite. Replace {name} and <token> accordingly.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Create Sprite and check runtime

Source: https://docs.fly.io/sprites/integrations/remote-mcp

Example request for the MCP connector that creates a Sprite named mcp-demo, runs python --version, and reports the installed runtime.

```text
Create a Sprite named mcp-demo, run python --version, and tell me what runtime is installed.
```

--------------------------------

### Install Ubuntu upgrader with apt

Source: https://docs.fly.io/sprites/sprite-maintenance

Install the Ubuntu upgrader to prepare for an in-place OS upgrade.

```bash
sudo apt update
sudo apt install ubuntu-release-upgrader-core

```

--------------------------------

### sprite create examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of creating a sprite with and without specifying a name or organization.

```bash
sprite create my-sprite
sprite create -o myorg development-sprite
sprite create
```

--------------------------------

### Install Fish Completion

Source: https://docs.fly.io/sprites/cli/installation

Install the fish completion script to the completions directory.

```bash
sprite completion fish > ~/.config/fish/completions/sprite.fish
```

--------------------------------

### Go: Start Service

Source: https://docs.fly.io/sprites/api/services/start-service

Uses net/http to POST to the start service endpoint. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### sprite login examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of the sprite login command: default login, specifying an organization with -o, and using a custom API URL. Also lists related commands for non-interactive token setup and organization management.

```bash
sprite login
sprite login -o my-org
sprite login https://custom-api.sprites.dev
Related Commands:
sprite auth --help      Non-interactive token setup (CI/CD)
sprite org --help       Manage organizations and tokens after login

```

--------------------------------

### Install Zsh Completion

Source: https://docs.fly.io/sprites/cli/installation

Enable completions and install the zsh completion script to your local functions.

```bash
echo "autoload -U compinit; compinit -i" >> ~/.zshrc
sprite completion zsh > ~/.local/share/zsh/site-functions/_sprite
# If the local functions directory isn't in your fpath
echo "fpath=(\"$HOME/.local/share/zsh/site-functions\" $fpath)" >> ~/.zshrc
```

--------------------------------

### sprite console examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of opening an interactive console, including specifying an organization and sprite.

```bash
sprite console
sprite console -o myorg -s mysprite

```

--------------------------------

### Prepare SSH server on Sprite

Source: https://docs.fly.io/sprites/working-with-sprites

Prepares an SSH server on the Sprite by installing OpenSSH and creating a service to start it automatically. Run these commands on the Sprite before attempting to mount its filesystem locally.

```bash
# Install OpenSSH
sudo apt install -y openssh-server

# Create a service to automatically start it
sprite-env services create sshd --cmd /usr/sbin/sshd
```

--------------------------------

### sprite checkpoint info usage and example

Source: https://docs.fly.io/sprites/cli/commands

Usage and example for the sprite checkpoint info command. The example shows how to display details for checkpoint v2.

```bash
sprite checkpoint info [flags] <version-id>

```

```bash
sprite checkpoint info v2              # Show details for checkpoint v2

```

--------------------------------

### Verify Sprites CLI Installation

Source: https://docs.fly.io/sprites/cli/installation

Run the help command to verify that the CLI is installed and accessible.

```bash
sprite --help
```

--------------------------------

### Java: Start Service

Source: https://docs.fly.io/sprites/api/services/start-service

Uses Unirest to POST to the start service endpoint. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.post("https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/start")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### sprite list examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of listing sprites with optional organization and prefix filters.

```bash
sprite list
sprite list -o myorg
sprite list --prefix dev
```

--------------------------------

### Install Pi Sprites plugin from GitHub

Source: https://docs.fly.io/sprites/integrations/agent-plugins

Installs the Pi extension for Sprites directly from GitHub using the pi install command. Requires Node.js 24 or newer.

```bash
pi install git:github.com/superfly/pi-sprites
```

--------------------------------

### Verify Sprite CLI installation

Source: https://docs.fly.io/sprites/quickstart

Verifies the Sprite CLI installation by displaying help information.

```bash
sprite --help

```

--------------------------------

### Service definition and state from sprite-env services get

Source: https://docs.fly.io/sprites/concepts/services

Example output of 'sprite-env services get web', showing the service definition plus live state. The state includes status, PID, and start time; 'restart_count' increments each time the runtime restarts the service after a crash.

```json
{
  "name": "web",
  "cmd": "python3",
  "args": ["-m", "http.server", "3000"],
  "http_port": 3000,
  "state": {
    "name": "web",
    "status": "running",
    "pid": 7353,
    "started_at": "2026-06-02T17:11:14.555839485Z"
  }
}

```

--------------------------------

### Install sprites-adk and set SPRITES_TOKEN

Source: https://docs.fly.io/sprites/integrations/agent-sdks

Install the sprites-adk package and set the SPRITES_TOKEN environment variable for authentication.

```bash
pip install sprites-adk
export SPRITES_TOKEN='...'

```

--------------------------------

### Go example to restart a service

Source: https://docs.fly.io/sprites/api/services/restart-service

Uses net/http to send a POST request with a Bearer token and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/restart"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get Checkpoint 200 Response Example

Source: https://docs.fly.io/sprites/api/checkpoints/get-checkpoint

Example 200 response for the Get Checkpoint endpoint. It shows a checkpoint object with a comment, creation time, and ID.

```json
{
  "comment": "Before database migration",
  "create_time": "2026-01-05T10:30:00Z",
  "id": "v7"
}
```

--------------------------------

### Go example for copy file or directory

Source: https://docs.fly.io/sprites/api/filesystem/copy-file-or-directory

Uses the net/http package to send a POST request with a JSON payload. The payload includes asRoot, dest, preserveAttrs, recursive, source, and workingDir.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/fs/copy"

	payload := strings.NewReader("{\n  \"asRoot\": true,\n  \"dest\": \"<string>\",\n  \"preserveAttrs\": true,\n  \"recursive\": true,\n  \"source\": \"<string>\",\n  \"workingDir\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get a sprite - 200 response

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

Example 200 response body for a successful GET request to the sprites endpoint.

```json
{
  "created_at": "2024-01-15T10:30:00Z",
  "id": "sprite-01234567-89ab-cdef-0123-456789abcdef",
  "name": "my-dev-sprite",
  "organization": "my-org",
  "status": "cold",
  "updated_at": "2024-01-15T14:22:00Z",
  "url": "https://name-random-alphanumeric.sprites.app",
  "environment_version": "v0.0.1-rc48",
  "labels": [
    "production"
  ],
  "last_running_at": "2024-01-15T14:20:00Z",
  "last_warming_at": "2024-01-15T14:22:00Z",
  "url_settings": {
    "auth": "sprite"
  },
  "version": "v0.0.1-rc48"
}
```

--------------------------------

### Get Service Logs Response Example

Source: https://docs.fly.io/sprites/api/services/get-service-logs

Example 200 response body for the Get Service Logs endpoint. Shows log entries with data, timestamp, and type fields, including a final complete entry with log file paths.

```json
[
  {
    "data": "Server started\n",
    "timestamp": 1735988400000,
    "type": "stdout"
  },
  {
    "data": "Handling request from 127.0.0.1\n",
    "timestamp": 1735988450000,
    "type": "stdout"
  },
  {
    "data": "Warning: slow query detected\n",
    "timestamp": 1735988455000,
    "type": "stderr"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988460000,
    "type": "complete"
  }
]
```

--------------------------------

### sprite auth setup - Set up authentication with token

Source: https://docs.fly.io/sprites/cli/commands

Set up authentication using a pre-generated token. The token must be in the format: org-slug/org-id/token-id/token-value.

```bash
sprite auth setup --token <token>

```

--------------------------------

### Get Service Logs with Java Unirest

Source: https://docs.fly.io/sprites/api/services/get-service-logs

Java example using Unirest to make a GET request for service logs. The response is stored as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Go example for change file owner

Source: https://docs.fly.io/sprites/api/filesystem/change-file-owner

Uses net/http to send a POST request with a JSON string body. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/fs/chown"

	payload := strings.NewReader("{\n  \"asRoot\": true,\n  \"gid\": {},\n  \"path\": \"<string>\",\n  \"recursive\": true,\n  \"uid\": {},\n  \"workingDir\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### Get Service Logs with PHP cURL

Source: https://docs.fly.io/sprites/api/services/get-service-logs

PHP example using cURL to perform a GET request for service logs. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Get Service 200 Response

Source: https://docs.fly.io/sprites/api/services/get-service

Example 200 response from the Get Service endpoint. Shows the service details including command, port, name, dependencies, and state.

```JSON
{
  "args": [
    "-m",
    "http.server",
    "8000"
  ],
  "cmd": "python",
  "http_port": 8000,
  "name": "webapp",
  "needs": [
    "postgres"
  ],
  "state": {
    "name": "webapp",
    "pid": 1567,
    "started_at": "2026-01-05T08:01:00Z",
    "status": "running"
  }
}
```

--------------------------------

### Global config file example

Source: https://docs.fly.io/sprites/cli/commands

Example of the global configuration file at ~/.sprites/sprites.json, managed by the CLI. The format may evolve.

```json
{
  "version": "1",
  "current_selection": {
    "url": "https://api.sprites.dev",
    "org": "personal"
  },
  "urls": {
    "https://api.sprites.dev": {
      "url": "https://api.sprites.dev",
      "orgs": {
        "personal": {
          "name": "personal",
          "keyring_key": "sprites-cli:<user-id>",
          "use_keyring": true,
          "sprites": {}
        }
      }
    }
  }
}

```

--------------------------------

### 200 response for Get a connector

Source: https://docs.fly.io/sprites/api/connectors/get-a-connector

Example 200 response for the Get a connector endpoint. The response contains a connection object with the connector's id and provider. Secrets and encrypted token fields are never returned.

```json
{
  "connection": {
    "id": "conn_abc123",
    "provider": "slack"
  }
}
```

--------------------------------

### Check Herdr Sprites plugin info

Source: https://docs.fly.io/sprites/integrations/agent-plugins

Checks the Sprite mapping and remote session, or see setup errors. A setup-launched response only means setup started; check the pane and run Info to confirm.

```bash
herdr plugin action invoke info --plugin sprites
```

--------------------------------

### List Checkpoints with Go

Source: https://docs.fly.io/sprites/api/checkpoints/list-checkpoints

Go example using net/http to list checkpoints. Replace {name} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/checkpoints"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Initialize QM deployment with Sprites backend

Source: https://docs.fly.io/sprites/integrations/platform-integrations

Initializes a QM deployment with the Sprites backend. Replace <slug> with your organization slug and <fly-or-aws> with fly or aws. Requires Node.js 24 or newer and a Sprites API token.

```bash
npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org <slug> --target <fly-or-aws>
npm install

```

--------------------------------

### Install and enable Sprites plugin for Grok Build

Source: https://docs.fly.io/sprites/integrations/agent-plugins

Install and enable the Sprites plugin for Grok Build. The --trust flag lets the plugin start its MCP connection. Review the repository before installing it and prefer the restricted OAuth policy unless Grok needs access to every Sprite in the organization.

```bash
grok plugin install superfly/sprites-grok-plugin --trust
grok plugin enable sprites

```

--------------------------------

### Create and manage Sprites with the JavaScript, Go, and Elixir SDKs

Source: https://docs.fly.io/sprites/quickstart

Use these SDK examples to programmatically create and manage Sprites from JavaScript, Go, or Elixir. Each demonstrates executing a short command and streaming output from a long-running command. Requires the SPDLITE_TOKEN environment variable.

```javascript
import { SpritesClient } from '@fly/sprites';

const client = new SpritesClient(process.env.SPRITE_TOKEN);

const sprite = await client.createSprite('my-sprite');

// Execute a command
const result = await sprite.execFile('python', ['-c', "print('hello')"]);
console.log(result.stdout);

// Stream output from long-running commands
const cmd = sprite.spawn('bash', ['-c', 'for i in {1..10}; do date +%T; sleep 0.5; done']);
for await (const line of cmd.stdout) {
  process.stdout.write(line);
}

await sprite.delete();
```

```go
package main

import (
    "context"
    "fmt"
    "io"
    "os"

    sprites "github.com/superfly/sprites-go"
)

func main() {
    ctx := context.Background()
    client := sprites.New(os.Getenv("SPRITE_TOKEN"))

    sprite, _ := client.CreateSprite(ctx, "my-sprite", nil)
    defer client.DeleteSprite(ctx, "my-sprite")

    // Execute a command
    cmd := sprite.Command("python", "-c", "print('hello')")
    output, _ := cmd.Output()
    fmt.Println(string(output))

    // Stream output from long-running commands
    cmd = sprite.Command("bash", "-c", "for i in {1..10}; do date +%T; sleep 0.5; done")
    stdout, _ := cmd.StdoutPipe()
    cmd.Start()
    io.Copy(os.Stdout, stdout)
    cmd.Wait()
}
```

```elixir
client = Sprites.new(System.get_env("SPRITE_TOKEN"))

{:ok, sprite} = Sprites.create(client, "my-sprite")

# Execute a command
{output, 0} = Sprites.cmd(sprite, "python", ["-c", "print('hello')"])
IO.puts(output)

# Stream output from long-running commands
sprite
|> Sprites.stream("bash", ["-c", "for i in {1..10}; do date +%T; sleep 0.5; done"])
|> Stream.each(&IO.write/1)
|> Stream.run()

Sprites.destroy(sprite)
```

--------------------------------

### Get a sprite with Java Unirest

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

Java example using Unirest to fetch a sprite. Replace {name} and <token> accordingly.

```java
HttpResponse<String> response = Unirest.get("https://api.sprites.dev/v1/sprites/{name}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Get a sprite with PHP cURL

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

PHP example using cURL to fetch a sprite. Replace {name} and <token> accordingly.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sprites.dev/v1/sprites/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Complete OAuth authorization with Go net/http

Source: https://docs.fly.io/sprites/api/connectors/complete-oauth-authorization

Go example using net/http to POST the OAuth callback and print the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/oauth/{provider}/callback"

	payload := strings.NewReader("{\n  \"code\": \"oauth-code\",\n  \"access_policy\": {\n    \"allow_all\": true\n  },\n  \"redirect_uri\": \"https://api.sprites.dev/v1/oauth/slack/callback\",\n  \"state\": \"opaque-state\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### Get a sprite with JavaScript fetch

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

JavaScript example using fetch to retrieve a sprite. Replace {name} and <token> accordingly.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sprites.dev/v1/sprites/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Python requests example

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses the requests library to perform a GET request to the read-file endpoint. Prints the response text.

```python
import requests

url = "https://api.sprites.dev/v1/sprites/{name}/fs/read"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Get a sprite with Python requests

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

Python example using the requests library to fetch a sprite. Replace {name} and <token> accordingly.

```python
import requests

url = "https://api.sprites.dev/v1/sprites/{name}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Complete OAuth authorization with Java Unirest

Source: https://docs.fly.io/sprites/api/connectors/complete-oauth-authorization

Java example using Unirest to POST the OAuth callback and get the response as a string.

```java
HttpResponse<String> response = Unirest.post("https://api.sprites.dev/v1/oauth/{provider}/callback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"oauth-code\",\n  \"access_policy\": {\n    \"allow_all\": true\n  },\n  \"redirect_uri\": \"https://api.sprites.dev/v1/oauth/slack/callback\",\n  \"state\": \"opaque-state\"\n}")
  .asString();

```

--------------------------------

### Get Service Logs with JavaScript fetch

Source: https://docs.fly.io/sprites/api/services/get-service-logs

JavaScript example using fetch to retrieve service logs and log the JSON response.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Local context file example

Source: https://docs.fly.io/sprites/cli/commands

Example of the local context file .sprite in the project directory, specifying the organization and sprite name.

```json
{
  "organization": "personal",
  "sprite": "my-project-sprite"
}

```

--------------------------------

### Ruby example to restart a service

Source: https://docs.fly.io/sprites/api/services/restart-service

Uses Net::HTTP to send a POST request with a Bearer token and prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/restart")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Java Unirest example

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses the Unirest HTTP library to send a GET request to the read-file endpoint. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.sprites.dev/v1/sprites/{name}/fs/read")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Install and enable the Sprites plugin

Source: https://docs.fly.io/sprites/integrations/cortex-code

Install the plugin from GitHub and enable it. Run these commands in the Cortex Code CLI.

```bash
cortex plugin install superfly/sprites-cortex-plugin
cortex plugin enable sprites

```

--------------------------------

### PHP cURL example

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses PHP cURL to send a GET request to the read-file endpoint. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sprites.dev/v1/sprites/{name}/fs/read",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### sprite proxy examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of forwarding local ports to the remote environment, including multiple ports, local:remote mapping, stdio forwarding, and specifying org/sprite.

```bash
sprite proxy 8080
sprite proxy 3000 8080
sprite proxy 4005:4000
sprite proxy 3001:3000 8081:8080
sprite proxy -W :22
sprite proxy -o myorg -s mysprite 8080
sprite proxy --ssh -s mysprite

```

--------------------------------

### JavaScript fetch example

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses the fetch API to make a GET request to the read-file endpoint. Logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sprites.dev/v1/sprites/{name}/fs/read', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Authorize an OAuth connector with Go

Source: https://docs.fly.io/sprites/api/connectors/authorize-an-oauth-connector

Go example using the net/http package to call the authorize endpoint. Replace {provider} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/oauth/{provider}/authorize"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get a sprite with Ruby Net::HTTP

Source: https://docs.fly.io/sprites/api/sprites/get-a-sprite

Ruby example using Net::HTTP to fetch a sprite. Replace {name} and <token> accordingly.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### POST /v1/sprites/{name}/services/{service_name}/start

Source: https://docs.fly.io/sprites/api/services/start-service

Starts a service within a sprite and monitors its startup logs.

```APIDOC
## POST /v1/sprites/{name}/services/{service_name}/start

### Description
Starts a service within a sprite and monitors its startup logs.

### Method
POST

### Endpoint
`https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/start`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the sprite.
- **service_name** (string) - Required - The name of the service to start.

#### Query Parameters
- **duration** (integer) - Optional - Time to monitor logs after starting (default: `5s`).

### Request Example
No request body is required.

### Response
#### Success Response (200)
Returns an array of log events.

#### Response Example
```json
[
  {
    "timestamp": 1735988400000,
    "type": "started"
  },
  {
    "data": "Starting server...\n",
    "timestamp": 1735988400000,
    "type": "stdout"
  },
  {
    "data": "Listening on port 8000\n",
    "timestamp": 1735988401000,
    "type": "stdout"
  },
  {
    "log_files": {
      "stdout": "/.sprite/logs/services/webapp.log"
    },
    "timestamp": 1735988402000,
    "type": "complete"
  }
]
```
```

--------------------------------

### sprite exec examples

Source: https://docs.fly.io/sprites/cli/commands

Examples of using sprite exec with various options: listing files, setting a working directory, passing environment variables, allocating a TTY, and specifying organization and sprite.

```bash
sprite exec -- ls -la
sprite exec --dir /app -- echo hello world
sprite exec --env KEY=value,FOO=bar -- env
sprite exec --tty -- /bin/bash
sprite exec -o myorg -s mysprite -- npm start

```

--------------------------------

### Get Service Logs with Python requests

Source: https://docs.fly.io/sprites/api/services/get-service-logs

Python example using the requests library to fetch service logs. Prints the response text.

```python
import requests

url = "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### List Directory API request examples

Source: https://docs.fly.io/sprites/api/filesystem/list-directory

Example requests for the List Directory endpoint. All use GET with the Authorization header set to 'Bearer <token>'. The path parameter {name} must be replaced with the sprite name, and the query parameters path and workingDir are required.

```cURL
curl --request GET \
  --url https://api.sprites.dev/v1/sprites/{name}/fs/list \
  --header 'Authorization: Bearer <token>'
```

```Python
import requests

url = "https://api.sprites.dev/v1/sprites/{name}/fs/list"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```JavaScript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sprites.dev/v1/sprites/{name}/fs/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sprites.dev/v1/sprites/{name}/fs/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sprites.dev/v1/sprites/{name}/fs/list"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```Java
HttpResponse<String> response = Unirest.get("https://api.sprites.dev/v1/sprites/{name}/fs/list")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}/fs/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Python: Start Service

Source: https://docs.fly.io/sprites/api/services/start-service

Uses the requests library to POST to the start service endpoint. Prints the response text.

```python
import requests

url = "https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/start"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)
```

--------------------------------

### Get Service Logs with Ruby Net::HTTP

Source: https://docs.fly.io/sprites/api/services/get-service-logs

Ruby example using Net::HTTP to fetch service logs. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}/services/{service_name}/logs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Create services with --needs dependency

Source: https://docs.fly.io/sprites/concepts/services

Create two services where the app starts only after postgres is ready, using the --needs flag.

```bash
# The database starts first
sprite-env services create postgres \
  --cmd /usr/lib/postgresql/16/bin/postgres \
  --args "-D,/home/sprite/pgdata"

# The app starts after postgres
sprite-env services create app \
  --cmd npm --args "start" \
  --dir /home/sprite/myapp \
  --needs postgres

```

--------------------------------

### Ruby Net::HTTP example

Source: https://docs.fly.io/sprites/api/filesystem/read-file

Uses Ruby's Net::HTTP library to send a GET request to the read-file endpoint. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}/fs/read")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Ruby example for copy file or directory

Source: https://docs.fly.io/sprites/api/filesystem/copy-file-or-directory

Uses Net::HTTP to send a POST request with a JSON body. The body includes asRoot, dest, preserveAttrs, recursive, source, and workingDir.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sprites.dev/v1/sprites/{name}/fs/copy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"asRoot\": true,\n  \"dest\": \"<string>\",\n  \"preserveAttrs\": true,\n  \"recursive\": true,\n  \"source\": \"<string>\",\n  \"workingDir\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
```
Tokens:
Raw