> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/openshell/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server.

# Protobuf time types

> Timestamp and duration representation in the OpenShell API

OpenShell represents absolute times with `google.protobuf.Timestamp` and
elapsed times with `google.protobuf.Duration` in its protobuf APIs.

Provider profile YAML and JSON accept canonical duration strings such as
`cache_ttl: "0.500s"`. The legacy `cache_ttl_seconds`, `refresh_before_seconds`,
and `max_lifetime_seconds` inputs remain supported for existing profiles.

In protobuf JSON, timestamps are RFC 3339 strings and durations are strings
ending in `s`:

```json
{
  "createdTime": "2026-08-31T14:05:06.123456789Z",
  "executionTimeout": "1.500s"
}
```

An absent message means that no timestamp or duration was supplied. It is
different from the Unix epoch (`1970-01-01T00:00:00Z`) and from a zero duration
(`0s`). OpenShell validates protobuf timestamp and duration bounds at API
boundaries.

## Upgrade from scalar time fields

The well-known time fields replace earlier public fields encoded as Unix
milliseconds, integer seconds, or duration strings. Their names and protobuf
tags changed, so clients generated from the old schema are not wire-compatible
with a gateway generated from the new schema. Upgrade the gateway, CLI, all SDK
clients, compute drivers, credential drivers, middleware services, and sandbox
supervisors together. Mixing versions can silently discard fields whose tags
changed. For example, the new gateway does not recognize an old credential
driver's tag-3 expiry and would treat that credential as non-expiring.

Before upgrading a gateway with persisted state:

1. Stop all gateway replicas.
2. Back up the SQLite database or PostgreSQL database.
3. Upgrade every gateway replica, client, driver, middleware service, and
   sandbox supervisor from the same OpenShell release.
4. Start one gateway replica and wait for startup to complete before starting
   the remaining replicas.

At startup, the gateway migrates affected protobuf payloads in one database
transaction. Legacy zero timestamps become absent. Zero expiry-map values are
removed, and the legacy maximum-integer refresh sentinel becomes an absent
next-refresh timestamp. The database columns `created_at_ms` and
`updated_at_ms` remain unchanged because they are internal ordering metadata.

If a legacy payload is malformed or outside protobuf time bounds, startup
fails with the affected object type and ID and rolls back the transaction.
Legacy sandbox condition transition strings that are not valid RFC 3339 are
dropped because earlier releases allowed arbitrary driver-provided strings.
Restore the backup or repair any other reported record with the previous
OpenShell version before retrying the upgrade.

User-facing timeout options and gateway TOML settings keep their existing
units. The CLI and SDKs convert those values at the protobuf boundary.