Policy Hub

The Ash Policy Hub hosts policies for common tools and use cases. Using policies from the Hub can simplify sandbox setup. You can also use the Hub to publish your own policies.

What is the Ash Policy Hub?

The Ash Policy Hub hosts policies for common use cases. Example policies:

All of the above policies are authored by the Ash team, but you can author and publish your own policies for distribution on the Policy Hub.

Using Ash Policy Hub

Add Dependencies

Add policies to your dependencies section:

schema_version: 1

dependencies:
  ash/base-macos: "1"
  ash/js-dev: "1"

files:
  rules:
    # Add project-specific rules
    - path: ~/projects/chowderhub/**

Version Requirements

Use SemVer requirement strings to specify versions:

dependencies:
  ash/base-macos: "1" # Any 1.x version
  ash/js-dev: "1.2" # Any 1.2.x version
  ash/python-dev: "=2.4.1" # Exact version only

SemVer syntax:

Combining Multiple Policies

You can depend on multiple policies:

dependencies:
  ash/base-macos: "1"
  ash/git-dev: "1"
  ash/js-dev: "1"
  ash/python-dev: "1"

Rules from all dependencies are merged into a single policy at the start of a session.

Policy Dependencies

Registry policies can depend on other policies. When you use a policy, Ash automatically resolves dependencies. For example, the github policy depends on the git policy.

Viewing Dependencies

Check what a policy depends on:

$ ash info ash/github
github v0.1.0

  Author: Ash <team@ashell.dev>
  License: MIT
  Registry: https://hub.ashell.dev/policies/ash/github
  
  Description:
  Policy for GitHub CLI and API access
  
  Dependencies:
  - ash/git: ^0

Caching

Registry policies are cached locally at ~/.ash/policies.

Ash looks for cached policies first before calling the registry. Run ash check while online to ensure all dependencies are cached before going offline.

Creating Your Own Policies

Local Policies

Local policies follow the same structure as registry policies:

# ~/policies/chowderbot-base.yml
schema_version: 1
files:
  rules:
    - path: ~/work/**
    - path: ~/.ssh/**
      action: deny
network:
  rules:
    - host: "*.chowderbot.test"
environment:
  rules:
    allow:
      - PATH
      - HOME
      - USER

Resolve a dependency to a local file with the path key:

dependencies:
  base-macos: "1"
  chowderbot-base:
    path: ~/policies/chowderbot-base.yml

Publishing to the Policy Hub

Publishing to the Policy Hub is WIP

To prepare a policy for publication:

1. Add required publish metadata:

schema_version: 1

publish:
  name: chowderbot/chowderbot
  version: 1.0.0
  description: Chowderbot cooking robot controls
  authors: ["Alice Adams <alice@chowderbot.test>"]
  license: MIT
  homepage: https://chowderbot.test
  repository: https://git.chowderbot.test/ash-policies

2. Test thoroughly
3. Publish to the registry

Dependency Restrictions

Published policies are classified as dependencies and thus restricted by the same rules as other dependency policies.

Best Practices

Start with Base Policies

Start with ash/base-macos and tool-specific policies:

dependencies:
  ash/base-macos: ^1.0
  ash/git: ^1.0
  ash/js-dev: ^1.0

files:
  rules:
    # Add your project-specific paths
    - path: ./**
    # Deny sensitive paths (policies are deny-by-default so this should be rare)
    - path: ~/.ssh/**
      action: deny

Review Before Using

Rview a registry policy before adding it:

ash info ash/base-macos

Check the expanded policy

Understand all access you are granting by looking at the fully resolved, expanded policy

ash expand

Keep Policies Updated

Check for updates periodically:

ash outdated

Troubleshooting

Policy Not Found

If a policy isn't found:

1. Check the policy name for typos
2. Verify the version exists
3. Check your network connection
4. Try clearing your local policy cache by deleting the ~/.ash directory

Version Conflicts

If you see version conflict errors:

Error: Conflicting versions of base-macos
  - ash/js-dev requires ">=1.0, <2.0"
  - ash/python-dev requires ">=1.5"

The resolver will find a compatible version if one exists. If not, you may need to update one of your dependencies.