Connect An HTTP Remote

Graft can fetch and push repository objects through a service that implements the Graft remote service protocol.

The wire contract is the implementation-independent Remote Service Protocol. This repository also ships the framework-neutral @eidos.space/graft-remote protocol engine, the @eidos.space/graft-remote-hono routing adapter, the reusable @eidos.space/graft-remote-cloudflare storage adapter, and a deployable Cloudflare reference service under services/graft-remote-cloudflare; Graft does not deploy it automatically.

Configure A Remote

Set the bearer token in the process environment, then add the remote:

export GRAFT_REMOTE_TOKEN='grt_...'
graft remote add origin \
  'https://example.com/acme/archive'

The URL follows the same visible shape as a Git HTTPS remote. The explicit graft+https://example.com/acme/archive alias selects the same transport and remains supported for compatibility.

Use token_env when the service token lives in a different variable:

export GRAFT_ARCHIVE_TOKEN='grt_...'
graft remote add origin \
  'https://example.com/acme/archive?token_env=GRAFT_ARCHIVE_TOKEN'

Do not put the token itself in the URI or .graft/config.toml.

Verify And Sync

Inspect the stored URL and advertised refs before pushing:

graft remote get-url origin
graft ls-remote origin
graft push origin main

On another worktree:

graft clone \
  'https://example.com/acme/archive' \
  main

The clone process needs the same token environment variable.

Local Protocol Development

Use graft+http:// only for a local server you control:

export GRAFT_REMOTE_TOKEN='dev-token'
graft remote add origin \
  'graft+http://127.0.0.1:8787/acme/archive'

For production, use HTTPS and let the service enforce repository authorization, object integrity, request limits, and durable storage.

Deploy The Cloudflare Reference Service

The verification service composes all three packages. The Cloudflare package provides authentication helpers, one SQLite Durable Object per repository for atomic refs, and R2 storage for immutable bytes. The service README contains bucket creation, secret configuration, local development, testing, and deployment commands.

For Hono on another platform, install @eidos.space/graft-remote-hono, mount createGraftRemote(), and implement its storage, authentication, and authorization interfaces. Other frameworks can build a thin routing adapter on @eidos.space/graft-remote; the core package has no Hono or Cloudflare dependency.

See Remote URIs for URI syntax and Sync With Remotes for branch workflows.