Tasks

​

When to use a task

• A background AI agent session — for example, an agent that reads your codebase, calls tools such as shell commands or database queries, and writes the results back to your project.
• A one-time job that needs service access: database maintenance, a data export, a report.
• A batch job triggered from your application rather than on a schedule.

• A long-running daemon: use a worker.
• A scheduled job: use a cron.
• Serving HTTP traffic: tasks are not routable and cannot be used as an upstream in routes:.

​

How tasks compare to other workloads

​

Define a task

​

Required fields

​

Common optional fields

​

Fields that don’t apply

​

Relationships

​

Trigger a task

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://api.upsun.com/projects/{project}/environments/{env}/tasks/myagent/run

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"BATCH_SIZE": "100", "TARGET": "prod"}}' \
  https://api.upsun.com/projects/{project}/environments/{env}/tasks/myagent/run

• A unique activity ID.
• Live status (pending, in_progress, complete, cancelled).
• Streamed logs through the existing activity logs endpoint.
• Cancellation through the /cancel endpoint on the activity.

​

Trigger from application code

​

1. Declare the authorization

​

2. Request a token and trigger the task

token=$(curl http://localhost:8200/oauth2/token -d grant_type=client_credentials | jq -r .access_token)

curl -X POST -H "Authorization: Bearer $token" \
  "https://api.upsun.com/projects/$PLATFORM_PROJECT/environments/$PLATFORM_BRANCH/tasks/myagent/run"

​

3. Cache the token

​

Sample implementation

import os
import time
import requests

_cache = {}

def _get_token():
    if _cache.get("expires_at", 0) - 30 > time.time():
        return _cache["token"]
    r = requests.post("http://localhost:8200/oauth2/token",
                      data={"grant_type": "client_credentials"},
                      headers={"x-token-ttl": "900"})  # 60–900 seconds
    r.raise_for_status()
    data = r.json()
    _cache["token"] = data["access_token"]
    _cache["expires_at"] = time.time() + data.get("expires_in", 900)
    return _cache["token"]

def trigger_task(task_name, variables=None):
    token = _get_token()
    project = os.environ["PLATFORM_PROJECT"]
    branch  = os.environ["PLATFORM_BRANCH"]
    r = requests.post(
        f"https://api.upsun.com/projects/{project}/environments/{branch}/tasks/{task_name}/run",
        headers={"Authorization": f"Bearer {token}"},
        json={"variables": variables} if variables else None,
    )
    r.raise_for_status()
    return r.json()

# Example: pass run-time variables
trigger_task("myagent", variables={"BATCH_SIZE": "100", "TARGET": "prod"})

​

Resources, variables, and access

• Resources (CPU, memory): configured by using upsun resources:set against the task name. Billing is per-second for the duration of each run.
• Variables and secrets: configured with upsun variable:create --level environment or by using the API. Sensitive variables are injected as environment variables at run time.
• Access: standard project roles apply. Project admins and contributors can change task definitions, trigger tasks, and view runs.

​

Security

​

Known limitations

• Cancelled on deploy. A running task receives SIGTERM before any deploy on the same environment, followed by SIGKILL after a grace period of a few seconds. Catch SIGTERM, persist state to a service, and exit cleanly. The caller is responsible for retrying.
• Concurrency cap. Multiple task runs can execute in parallel up to a default limit of 3. Further triggers queue behind running ones.
• No task-to-task relationships. Nothing can declare a relationship to a task. An app and a task can share a relationship to the same service or a network file mount.
• Fresh filesystem every run. instance and tmp mounts are reset between runs. Use a storage or service mount for files that must survive across runs.
• Requires at least one application. A project with only tasks and services is not currently valid.
• Minimal Console and CLI support. Task activities appear in the activity feed, but there is no dedicated task UI as part of this Prerelease program.