Install

epack install remote locktivity

Adds to epack.yaml, resolves dependencies, downloads binary.

Usage

Push an evidence pack to the remote registry:

epack push locktivity ./evidence.pack

Uploads the pack and creates a release in the remote registry.

Configuration

Or add manually to epack.yaml:

remotes:
  locktivity:
    source: https://github.com/locktivity/epack-remote-locktivity

Then run epack install to lock and sync.

Locktivity Remote Overview

The Locktivity remote adapter connects epack to the Locktivity registry for evidence pack distribution and run ledger synchronization.

What It Does

Capability	Description
Push	Creates a pack record, uploads via presigned URL, and finalizes a release
Pull	Resolves and downloads the latest release, or a specific release by ID
Run Sync	Sends run ledger metadata tied to a pack digest
Whoami	Returns whether current credentials are authenticated

Request Flow

Push

push.prepare creates or resolves a pack by file digest and returns upload info.
- stream is extracted from the uploaded pack during ingestion
- Stream provenance is validated as part of pack verification, not as an explicit API parameter
The pack is uploaded directly to storage.
push.finalize creates the Locktivity release.

Pull

pull.prepare resolves a release reference.
The adapter fetches a download URL for the associated pack.
pull.finalize confirms completion to the caller.

Supported pull refs today:
- Latest release (epack pull locktivity)
- Release ID (epack pull locktivity --release <id>)
- Version lookup (epack pull locktivity --version ...)
- Digest lookup (epack pull locktivity --digest ...)

Lookup scoping currently uses target.environment from the remote target.

Run Sync

runs.sync posts run IDs, result paths, and digests for a given pack digest.

Authentication

The adapter accepts a pre-resolved access token when one is injected into the
environment:

export LOCKTIVITY_ACCESS_TOKEN="your-short-lived-token"

Manual client credentials remain supported:

export LOCKTIVITY_CLIENT_ID="your-client-id"
export LOCKTIVITY_CLIENT_SECRET="your-client-secret"

Interactive device-code login is available for local/manual use when
LOCKTIVITY_AUTH_MODE=all.

Security Model

API calls use HTTPS.
Upload/download transfer uses time-limited presigned URLs.
Custom endpoints require explicit acknowledgement, must use HTTPS, and are blocked by EPACK_STRICT_PRODUCTION=true.
When custom endpoints are active, the adapter emits an insecure-bypass audit event.

Limits

Limit	Value
Max pack size	100 MB

Locktivity Remote Configuration

epack.yaml Setup

Add a Locktivity remote:

remotes:
  locktivity:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET

The secrets list is required so epack will pass these environment variables
through to the remote adapter process.

For brokered or managed-runner setups, epack may instead inject
LOCKTIVITY_ACCESS_TOKEN on the adapter's behalf. The adapter will always prefer
that short-lived access token over any local OAuth flow.

Custom endpoints belong in config and require explicit acknowledgement:

remotes:
  locktivity-dev:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    insecure_endpoint: https://dev-tunnel.ngrok-free.app
    auth:
      insecure_endpoint: https://dev-tunnel.ngrok-free.app

You can define multiple remotes for different environments:

remotes:
  locktivity-prod:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET
    target:
      environment: production

  locktivity-staging:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET
    target:
      environment: staging

Authentication Configuration

Manual Client Credentials

export LOCKTIVITY_CLIENT_ID="your-client-id"
export LOCKTIVITY_CLIENT_SECRET="your-client-secret"
epack push locktivity packs/evidence.epack

Brokered Access Token

export LOCKTIVITY_ACCESS_TOKEN="your-short-lived-token"
epack push locktivity packs/evidence.epack

Interactive Device Code Login

Set LOCKTIVITY_AUTH_MODE=all to enable interactive login and stored-token
refresh flows.

Runtime Override Environment Variables

The preferred path is epack.yaml, but the adapter also accepts explicit runtime overrides:

EPACK_REMOTE_ENDPOINT – trusted API endpoint passed by epack from insecure_endpoint config
EPACK_REMOTE_AUTH_ENDPOINT – trusted auth endpoint passed by epack from auth.insecure_endpoint config

For standalone/manual use, LOCKTIVITY_ENDPOINT and LOCKTIVITY_AUTH_ENDPOINT are accepted
as backward-compatible aliases. All custom endpoints must use HTTPS.

Troubleshooting

"authentication required"

Set one of the supported auth inputs:
- LOCKTIVITY_ACCESS_TOKEN
- LOCKTIVITY_CLIENT_ID
- LOCKTIVITY_CLIENT_SECRET

For client credentials, set both:
- LOCKTIVITY_CLIENT_ID
- LOCKTIVITY_CLIENT_SECRET

Pull by version returns not found

Ensure the specified version exists in the target environment and that your credentials include release read access.

Locktivity Remote Examples

Basic Push/Pull

# epack.yaml
remotes:
  locktivity:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET

# Push a local pack
epack push locktivity packs/evidence.epack

# Pull latest release
epack pull locktivity

Brokered Access Token

export LOCKTIVITY_ACCESS_TOKEN="your-short-lived-token"
epack push locktivity packs/evidence.epack

Custom Development Endpoint

remotes:
  locktivity-dev:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    insecure_endpoint: https://dev-tunnel.ngrok-free.app
    auth:
      insecure_endpoint: https://dev-tunnel.ngrok-free.app

epack push locktivity-dev packs/evidence.epack

Pull by Release ID

epack pull locktivity --release rel_abc123

Collector Run + Push

# Build a pack from configured collectors
epack collector run --output packs/evidence.epack

# Push pack (run sync is handled during push unless --no-runs is set)
epack push locktivity packs/evidence.epack

Environment-Specific Remotes

remotes:
  locktivity-prod:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET
    target:
      environment: production

  locktivity-staging:
    adapter: locktivity
    source: locktivity/epack-remote-locktivity@v1
    secrets:
      - LOCKTIVITY_CLIENT_ID
      - LOCKTIVITY_CLIENT_SECRET
    target:
      environment: staging

epack push locktivity-staging packs/evidence.epack
epack push locktivity-prod packs/evidence.epack

Client Credentials in CI

jobs:
  push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build pack
        run: epack collector run --output packs/evidence.epack

      - name: Push pack
        env:
          LOCKTIVITY_CLIENT_ID: ${{ secrets.LOCKTIVITY_CLIENT_ID }}
          LOCKTIVITY_CLIENT_SECRET: ${{ secrets.LOCKTIVITY_CLIENT_SECRET }}
        run: epack push locktivity packs/evidence.epack

v0.1.5 Latest

2026-03-31

**Full Changelog**: https://github.com/locktivity/epack-remote-locktivity/compare/v0.1.4...v0.1.5