SI FabrikDocs
/
sifabrik.com ↗
Projects

Project links

Let a project's agents install private packages, use another project's code, and reach the services its app calls, without loosening the sandbox by hand.

Projects rarely stand alone. The links: block tells SI Fabrik what a project uses, so its agents can install packages, reach the APIs the app calls, and test against code from other projects. SI Fabrik turns each link into allowlist entries, credentials wiring and notes for the agent.

Packages#

A package link is a dependency the agent needs to install.

WORKFLOW.md
links:
  packages:
    - name: "@your-scope/ui-kit"
      from: registry                        # a published version
      registry: https://npm.example.com/
      token_env: NPM_REGISTRY_TOKEN               # set in Edit Project → Environment
    - name: "@your-scope/utils"
      from: git                             # a git dependency (https only)
      url: https://gitlab.example.com/team/utils.git
      ref: v2.3.0                           # optional branch, tag or commit
      token_env: GIT_DEP_TOKEN
      # username: oauth2                    # default; sent with the token
    - name: "@your-scope/shared"
      from: source                          # another SI Fabrik project's code, read-only
      project: shared-lib
      ref: main                             # default: that project's base branch
fromRequired keysWhat SI Fabrik does
registryregistry (http or https URL)Adds the registry host to the allowlist. With token_env, npm gets a SI Fabrik-only config (NPM_CONFIG_USERCONFIG) containing ${NPM_REGISTRY_TOKEN}, scoped to the package's npm scope.
giturl (https)Adds the git host to the allowlist. With token_env, git gets a credential helper that reads the variable when it's needed.
sourceprojectMounts the other project's committed code at the ref, read-only, at /deps/<project> in Docker or ~/deps/<project> in Cloudflare.

About source links:

  • The code is exported with git archive from that project's own repository, so untracked files such as .env aren't included.
  • The agent is told to build and install it from a copy, without saving the change to package.json or the lockfile.
  • The linked project's own registries are allowed too, so its code can be built.
  • Snapshots are kept under ~/Library/Application Support/Harness/links/<project>/<commit>/.

Token values stay in the environment. They're never written to a file or the repository, and URLs can't carry credentials (use token_env).

Services#

A service link is something the app calls at runtime. The agent and the app get its address in an environment variable.

WORKFLOW.md
links:
  services:
    - name: api
      env: API_URL                          # the agent and the app get the address here
      url: https://staging-api.example.com  # a hosted environment
    - name: auth
      env: AUTH_URL
      project: auth-service                 # run that project's app next to the agent
      ref: main                             # optional
      # port: 4000                          # optional: overrides its preview.port

Hosted (url:): the host is allowlisted and the URL goes in the variable. The agent is told it's a shared environment.

Run next to the agent (project:, Docker only): the linked project's app starts in its own hardened container at the ref, using that project's preview: command, its own environment (docker.env) and its own allowlist.

  • The agent reaches it at $AUTH_URL, through its allowlist, but can't read its secrets.
  • Its output goes to .harness/services/<name>.log in the workspace.
  • It stops with the attempt.
Note

A service that runs next to the agent needs Docker. For projects on Cloudflare sandboxes, use a hosted url: service instead.

Sharing: both sides agree#

A project's code and services are only used by projects it names in share_with. The linked project opts in, in its own WORKFLOW.md:

auth-service/WORKFLOW.md
share_with: [shop-storefront]

Open Workflow → Settings → Links:

  • Add package: name, Comes from (A package registry, A git repository or Another SI Fabrik project's code), the URL or project, Branch, tag or commit, Username for git, and an optional Token variable.
  • Add service: name, Address variable, Runs (Hosted (a URL) or Next to the agent (another SI Fabrik project)), and the URL or project with an optional ref and port.
  • Share with: projects allowed to use this one.
  • Accept tasks from and Their tasks land in: see Linked tasks.

When you pick a project, the form shows whether it already shares with this one, or what's missing.

Rules and problems#

  • Names in env must be environment-variable names, used once. Credential and reserved names (ANTHROPIC_API_KEY, HARNESS_GITHUB_TOKEN, and so on) are refused.
  • Push, tracker and model credentials can't be used as link tokens: CLICKUP_API_TOKEN, LINEAR_API_KEY, GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN, the agent credentials and SI Fabrik's own HARNESS_* tokens.
  • Problems block dispatch with a clear reason, and show in the Workflow tab's inspector under Links. For example: a project that doesn't share back, a missing token, an invalid ref, or a service on Cloudflare.

See also#