Documentation: 0.5.0 (source: v0.5.0).
# Starbases

> A player's own state at a starbase — cargo, escrowed ships, and upgrades in progress.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/starbases/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

A starbase is where fleets dock, cargo is stored, and crafting happens. The SDK
splits it in two, and knowing which half you want saves confusion.

- **The starbase itself** — where it is, what level it is — is shared
  infrastructure and belongs to [world](/guides/world/).
- **Your state at that starbase** — your cargo, your escrowed ships, your
  upgrades — is yours, and lives here.

:::game[A starbase anchors a system]
A starbase is the main harbour and service centre of a star system. Players
from the faction that controls it can dock fleets, store cargo, trade on the
local market, craft goods, make repairs, and support work on nearby planets.
It also marks who controls the system. Rival factions cannot simply use it as
their own base, but they can fight to take control of it.
:::

## Reading your state at a starbase

```ts
const bases = await character.starbases.all();
```

Or directly, when you know the system:

```ts
const base = await sage.starbases.forCharacterAtSystem(
  characterAddress,
  systemAddress,
);
```

A character can have state at many starbases, or none. A character who has
never docked anywhere returns an empty array, which is a valid answer rather
than a failed read.

> **Runnable example — Read a character's starbases.** List the starbases where a character has presence, and one base upgrades list. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/starbases/.

## What is in it

**Cargo.** What you have stored there, as `StarbaseCargoInventory`. This is
distinct from what a fleet is carrying — cargo moves between the two, and
reading one tells you nothing about the other.

**Escrowed ships.** Ships you own that are held at the starbase rather than
assigned to a fleet.

**Respawn state.** Where destroyed ships come back.

**Upgrades in progress.** Starbase upgrades take real time, so an upgrade is a
process with a lifecycle rather than an instant change:

```ts
const upgrades = await base.upgrades.all();
```

:::game[Higher tiers expand a starbase's reach]
A higher-tier starbase can support more activity in its system. Upgrades can
strengthen the base, improve the services around it, and allow more Claim
Stakes to operate on nearby planets. They can also make the system more useful
as part of a travel and trade route. Bigger starbases need more materials and
upkeep, so the controlling faction must keep supporting them after the upgrade
is finished.
:::

## Gotchas

**Starbase cargo and fleet cargo are different accounts.** Loading a fleet does
not change what the starbase holds, and vice versa. If you are tracking totals,
you need both.

**A starbase you have never used has no player state.** The starbase exists in
the world; your state at it does not. That is why the read can legitimately
come back empty.

**Upgrade timing is derived.** Completion times come from the process state
plus the Game account's definitions, not from a stored timestamp you can read
directly.

## Reference

- [`starbases`](/reference/starbases/) — every export in this entry
- [`world`](/guides/world/) — the starbase as shared infrastructure
- [`crafting`](/guides/crafting/) — what happens at a starbase's habs