---

name: deploying-to-globe description: Deploys Dart and Flutter applications to Globe.dev serverless platform. Use when deploying apps, configuring globe.yaml, Globe KV, Globe DB, Globe AI, cron jobs, custom domains, environment variables, or troubleshooting Globe errors.

Globe Deployment Skill

Globe is a serverless deployment platform for Dart and Flutter applications. Apps compile to x86_64 native executables and deploy to 300+ edge locations with automatic scaling.

Critical Requirements

All Globe server apps MUST:

1. Listen on PORT environment variable (not hardcoded):

Copyfinal port = int.parse(Platform.environment['PORT'] ?? '8080');

1. Be stateless — no local file persistence between requests

2. Compile FFI to x86_64 if using native code

CLI Quick Reference

Copy# Install
dart pub global activate globe_cli

# Auth
globe login
globe logout

# Project Management
globe link              # Link existing project
globe unlink            # Unlink project
globe create -t <tpl>   # New project from template

# Deploy
globe deploy            # Preview deployment
globe deploy --prod     # Production deployment
globe build-logs        # Stream build logs

# Tokens (for CI/CD)
globe token create
globe token list
globe token delete

Global flags: --help, --verbose, --token <t>, --project <id>, --org <id>

globe.yaml (Optional)

Globe auto-detects most project types. A globe.yaml is required for:

• Cron jobs — must be defined in config file
• Static assets — must be defined in config file

Other settings (preferred regions, build settings, etc.) can be configured via the dashboard instead.

Example (when needed):

Copy# yaml-language-server: $schema=https://globe.dev/globe.schema.json

entrypoint: bin/server.dart

build:
  preset:
    type: dart_frog # or: shelf, flutter, jaspr, serverpod

# These require globe.yaml:
assets:
  - public/

crons:
  - id: daily_cleanup
    schedule: "0 0 * * *"
    path: "/cron/cleanup"

Validate (if globe.yaml exists):

Copybash scripts/validate-globe-yaml.sh globe.yaml

Build Presets

Common Code Patterns

Shelf Hello World

Copyimport 'dart:io';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;

void main() async {
  final port = int.parse(Platform.environment['PORT'] ?? '8080');
  final handler = const Pipeline()
      .addMiddleware(logRequests())
      .addHandler((req) => Response.ok('Hello from Globe!'));
  await io.serve(handler, InternetAddress.anyIPv4, port);
}

Environment Variables

Copy// User-defined secrets (set in Globe dashboard)
final apiKey = Platform.environment['API_KEY'];
final dbUrl = Platform.environment['DATABASE_URL'];

// Globe system variables (auto-set)
final isGlobe = Platform.environment['GLOBE'] == '1';
final buildEnv = Platform.environment['GLOBE_BUILD_ENV']; // 'preview' or 'production'

Cron Job Handler

Copy// Cron jobs POST to your path at scheduled times
app.post('/cron/daily', (Request req) async {
  final cronId = req.headers['x-globe-cron-id'];
  // Do work...
  return Response.ok('done'); // 2xx = success
});

Globe KV (Key-Value Store)

Copyimport 'package:globe_kv/globe_kv.dart';

final kv = GlobeKV('namespace-id'); // Create namespace in dashboard first

await kv.set('key', 'value', ttl: 3600);  // TTL in seconds
final value = await kv.getString('key');
await kv.delete('key');
final keys = await kv.list(prefix: 'user:', limit: 100);

Globe DB (SQLite)

Copyimport 'package:drift/drift.dart';
import 'package:drift/native.dart';
import 'package:sqlite3/sqlite3.dart';

// Connect to Globe DB (name from dashboard)
final db = NativeDatabase.opened(sqlite3.open('your-db-name.db'));

Globe AI

Copyimport 'package:globe_ai/globe_ai.dart';

final result = await generateText(
  model: openai.chat('gpt-4o'),
  prompt: 'What is the capital of France?',
);

globe.yaml Full Example

Copy# yaml-language-server: $schema=https://globe.dev/globe.schema.json

entrypoint: bin/server.dart

build:
  preset:
    type: dart_frog
    version: "2.0.0" # Optional: pin framework version
    buildCommand: "custom" # Optional: override build command
  build_runner:
    automatic_detection: true
    command: "dart run build_runner build" # Optional override
  melos:
    automatic_detection: true # For monorepos
    command: "melos bootstrap"
    version: "3.0.0"

assets:
  - public/
  - assets/images/

crons:
  - id: daily_cleanup # 1-50 chars, alphanumeric + underscores
    schedule: "0 0 * * *" # Cron expression (midnight UTC)
    path: "/cron/cleanup"

preferred_regions: # See full list below
  - us-east1
  - europe-west1

Preferred Regions

Valid values for preferred_regions:

Copyafrica-south1, asia-east1, asia-east2, asia-northeast1, asia-northeast2,
asia-northeast3, asia-south1, asia-south2, asia-southeast1, asia-southeast2,
australia-southeast1, australia-southeast2, europe-central2, europe-north1,
europe-southwest1, europe-west1, europe-west2, europe-west3, europe-west4,
europe-west6, europe-west8, europe-west9, europe-west10, europe-west12,
me-central1, me-central2, me-west1, northamerica-northeast1, northamerica-northeast2,
northamerica-south1, southamerica-east1, southamerica-west1, us-central1,
us-east1, us-east4, us-east5, us-south1, us-west1, us-west2, us-west4

System Environment Variables

Globe Request Headers

Globe adds these headers to incoming requests:

• x-globe-country — ISO country code
• x-globe-city — City name
• x-globe-region — Region/state
• x-globe-latitude / x-globe-longitude — Coordinates
• x-globe-timezone — IANA timezone
• x-globe-temperature — cold, warm, or hot (container state)

Resource Limits

Error Quick Fixes

Reference Documentation

Load the appropriate reference file based on user intent. For topics not listed, explore the references/ folder.

Getting Started

Core Concepts

CLI Commands

Frameworks

Products

Infrastructure

Guides

Tutorials

Troubleshooting

Deployment Workflow

Copy this checklist and track progress:

CopyDeployment Progress:
- [ ] Step 1: Verify PORT usage in code
- [ ] Step 2: Create globe.yaml (only if needed for crons/assets/regions)
- [ ] Step 3: Set environment variables in dashboard (if needed)
- [ ] Step 4: Run `globe deploy` for preview
- [ ] Step 5: Test preview URL
- [ ] Step 6: Run `globe deploy --prod` for production
- [ ] Step 7: Configure custom domain (if needed)

Step 1: Ensure server listens on Platform.environment['PORT']

Step 2: Create globe.yaml only if you need cron jobs or static assets. Globe auto-detects presets for most projects.

Step 3: Add secrets via Dashboard → Settings → Environment Variables

Step 4: Deploy preview: globe deploy

Step 5: Test the preview URL thoroughly

Step 6: Deploy production: globe deploy --prod

Step 7: Add custom domain via Dashboard → Domains → CNAME to domains.globeapp.dev

Decision Tree

CopyDeploying Dart/Flutter to Globe?
├── New project?
│   ├── Yes → globe create -t <template>
│   └── No → globe link
│
├── Framework?
│   ├── Dart Frog → preset: dart_frog (auto-detected)
│   ├── Shelf → preset: shelf
│   ├── Flutter Web → preset: flutter
│   └── Jaspr → preset: jaspr
│
├── Deployment type?
│   ├── Preview → globe deploy
│   └── Production → globe deploy --prod
│
├── Needs caching?
│   └── Globe KV → Create namespace in dashboard, use globe_kv package
│
├── Needs database?
│   └── Globe DB → Create in dashboard, use Drift with sqlite3
│
├── Needs AI?
│   └── Globe AI → Install globe_ai, configure model provider
│
├── Background jobs?
│   └── Add crons to globe.yaml, handler returns 2xx
│
├── Custom domain?
│   └── Dashboard → Domains → Add → CNAME to domains.globeapp.dev
│
└── CI/CD?
    ├── GitHub → Enable GitHub integration
    └── Other → globe token create