Skip to content

What Runs as a Pod and Why

Jump to bottom
Adrian Burlacu edited this page Feb 6, 2026 · 3 revisions

What Runs as a Pod (and Why)

In Stark, the unit of distribution is a pack — a software package with code, metadata, and configuration.
When executed, a pack becomes a pod — a running process managed by the orchestrator.

This page explains the pod abstraction in Stark Orchestrator and what types of workloads are suited to run as pods.

Packs Are the Unit of Distribution

A pack contains:

  • application code
  • dependencies
  • config and metadata
  • lifecycle information

Packs are immutable artifacts that describe how software should run.

This mirrors the concept of software packages used by package managers like npm, pip, etc.

Pods Are the Unit of Execution

A pod is a running instance of a pack on a specific node. It's the atomic unit of execution in Stark.

Pack (code) + Node (runtime) = Pod (execution)

A pod in Stark is a running process that:

  • executes code from a pack
  • has a lifecycle
  • can fail and be restarted
  • is scheduled on a node or runtime

Pod Lifecycle

Pods progress through these states:

┌─────────┐     ┌───────────┐     ┌─────────┐
│ Pending │ ──► │ Scheduled │ ──► │ Running │
└─────────┘     └───────────┘     └────┬────┘
                                       │
                          ┌────────────┼────────────┐
                          ▼            ▼            ▼
                    ┌───────────┐ ┌────────┐ ┌──────────┐
                    │ Succeeded │ │ Failed │ │ Stopping │
                    └───────────┘ └────────┘ └────┬─────┘
                                                  ▼
                                            ┌─────────┐
                                            │ Stopped │
                                            └─────────┘
State Description
Pending Pod created, waiting for scheduling
Scheduled Assigned to a node, waiting for execution
Running Actively executing on the node
Succeeded Completed successfully
Failed Execution failed
Stopping Graceful shutdown in progress
Stopped Terminated (either by user or system)

What Should Run as a Pod?

✅ Good Candidates

Workload Runtime Why
API handlers Node.js Stateless, scalable
Background workers Node.js Long-running processes
Cron jobs Node.js Scheduled tasks
UI applications Browser Self-contained apps
Widget components Browser Embeddable UI pieces
Data processors Either Compute-intensive tasks

❌ Not Ideal For

Workload Better Alternative
Databases Use managed databases (Supabase, etc.)
File storage Use object storage (S3, etc.)
Stateful services Consider persistent storage solutions
System daemons Use traditional service

Pod Configuration

When creating a pod, you can specify:

node packages/cli/dist/index.js pod create \
  --pack my-pack \              # Pack to run
  --node my-node \              # Target node (optional)
  --namespace production \      # Namespace isolation
  --priority 200 \              # Scheduling priority
  --label app=web \             # Pod labels
  --cpu 500 \                   # CPU millicores
  --memory 256                  # Memory MB

Resource Requests

Pods declare resource requirements:

Resource Unit Description
CPU Millicores 1000 = 1 CPU core
Memory MB RAM allocation

The scheduler ensures nodes have sufficient capacity before assigning pods.

Pod vs Service

Aspect Pod Service
Lifecycle Manual Managed
Auto-healing None Yes
Scaling Create more pods Single command
Use case One-off tasks Production workloads

For production workloads, use Services for automatic management.

Why UI Runs as a Pack

In Stark, user interfaces are not special.
They are packs that become pods.

This means:

  • UI can crash without taking down the system
  • UI can restart independently
  • multiple UIs can exist simultaneously
  • headless operation is trivial

Interfaces are workloads, not privileges.

System Packs vs User Packs

Stark distinguishes:

  • system packs — trusted, introspective, privileged
  • user packs — constrained, isolated, limited

This allows safe operation while enabling extensibility.

The Rule

If software can run, fail, be observed, and be restarted — ⇒ it is instantiated as a pod.
If software can be installed, versioned, distributed — ⇒ it is a pack.

Nothing else.

That's Stark's model.

TODO: Additional Documentation

Related Topics

Clone this wiki locally