StackShift Functions

​

Goal

​

Prerequisites

• A GitHub-backed project or Docker image project that contains an api/ directory
• Node.js handler files under api/ using JavaScript or TypeScript
• At least one healthy node running the Phase 4 agent

​

Workflow

​

Project layout

api/
  hello.js
  users/
    [id].ts
stackshift.functions.json
package.json

​

HTTP handlers

export async function GET(request, context) {
  return Response.json({
    message: 'Hello from StackShift Functions',
    requestId: context.requestId,
  })
}

export async function POST(request) {
  const body = await request.json()
  return Response.json({ received: body }, { status: 201 })
}

export async function GET(_request: Request, context: { params: { id: string } }) {
  return Response.json({ userId: context.params.id })
}

​

Function configuration

• HTTP timeout must be positive and within the supported HTTP limit.
• Async, queue, and scheduled functions may use longer timeouts than HTTP handlers.
• Supported memory values are 128m, 256m, 512m, and 1g.
• Retries apply to non-HTTP work and are capped by the platform.
• Use one explicit queue name per function in v1. background: true remains supported and maps to the built-in _async queue.

{
  "functions": {
    "api/hello.js": {
      "timeout": 10,
      "memory": "128m"
    },
    "api/process-image.js": {
      "background": true,
      "timeout": 300,
      "memory": "512m",
      "retries": 3
    },
    "api/thumbnail.js": {
      "queue": "images",
      "timeout": 300,
      "retries": 5
    },
    "api/cleanup.js": {
      "schedule": "0 * * * *",
      "timeout": 60
    }
  }
}

​

Async invocation and queues

import { enqueue, invoke } from '@stackshift/functions'

export async function POST(request, context) {
  const payload = await request.json()

  await invoke('api/process-image.js', payload, {
    requestId: context.requestId,
  })

  await enqueue('images', payload, {
    requestId: context.requestId,
  })

  return Response.json({ queued: true }, { status: 202 })
}

​

Schedules

• Supported aliases: @hourly, @daily, and @weekly.
• Supported intervals: @every 15m, @every 2h, and similar positive durations.
• Supported simple cron forms include */10 * * * *, 0 * * * *, and 0 */2 * * *.
• When a scheduled function is removed from the manifest, StackShift disables the stale scheduled job.
• Failed scheduled runs appear in the project Runs view and can be replayed from there.

export async function run(context) {
  console.log('cleanup started', {
    scheduledAt: context.scheduledAt,
    requestId: context.requestId,
  })

  // remove expired records, rotate caches, or sync external state
}

​

Routing and cold starts

• Caddy adds X-StackShift-Functions-Runtime so the gateway knows which project runtime to use.
• The gateway cold-starts app_<runtimeID> when the function is inactive and waits for __stackshift/health.
• Idle containers are stopped after the configured idle timeout and restarted on the next request.
• Reserved internal invoke paths require X-StackShift-Internal-Token before any cold start is attempted.

​

Environment variables

• PORT: the port used by the generated runtime; defaults to the project runtime port, commonly 3000.
• STACKSHIFT_FUNCTIONS_ASYNC_URL: private StackShift endpoint used by @stackshift/functions to create durable async runs in deployed environments.
• STACKSHIFT_FUNCTIONS_ASYNC_TOKEN: private per-project token used to authorize async enqueue requests.
• STACKSHIFT_PROJECT_ID: injected project identifier used by the helper when submitting async or queue work.
• STACKSHIFT_FUNCTIONS_INVOKE_TOKEN: private token still used by the internal gateway/runtime invoke path.
• STACKSHIFT_FUNCTIONS_INVOKE_URL: optional local override for unusual topologies. Leave it unset in normal production; the compatibility default remains http://127.0.0.1:$PORT/.stackshift/functions/invoke inside the runtime container.
• FUNCTIONS_ROOT and FUNCTIONS_MANIFEST: generated runtime paths. Override only for custom runtime debugging.

​

Production URL guidance

• Do not expose STACKSHIFT_FUNCTIONS_ASYNC_TOKEN or STACKSHIFT_FUNCTIONS_INVOKE_TOKEN to browsers, client bundles, or public logs.
• Do not point your frontend directly at the private async helper endpoint.
• Do keep normal platform API clients pointed at https://api.stackshift.cloud/api/v1 when they are calling the public StackShift API.

​

Operational checklist

• Confirm the project workload type is functions after detection or manual override.
• Check build logs for manifest warnings about missing configured source files, duplicate queue names, or invalid schedules.
• Check deployment logs for gateway registration, Caddy route updates, and cold-start errors.
• Use the Functions overview for HTTP endpoints, queues, schedules, and runs before dropping down to raw durable-jobs internals.
• Use function logs for [stackshift-functions] entries including request ID, function path, status, duration, trigger type, run ID, and timeout state.
• Replay failed schedule and queue runs or retry failed async runs from the project Runs view.

​

Expected result

​

Common failures

​

Related guides