Setting Up VS Code for Local Foundry Code Repository Development (macOS)¶

Standard Operating Procedure · Version 1.0 · Last Updated: May 12, 2026
Scope: macOS (Apple Silicon or Intel) for Local Foundry Code Repository Development

Executive Summary¶

Requirement	Specification
Java Version	OpenJDK 17 must be installed and configured in `JAVA_HOME`
Node.js Version	Node.js 24 (LTS) installed via NVM
Authentication	Bearer Token must be configured in `~/.gradle/gradle.properties`
Environment	VS Code must be configured to inherit environment variables via `settings.json`

1. Overview¶

This SOP provides a comprehensive guide to setting up a local macOS development environment for Palantir Foundry code repositories. Following these steps ensures compatibility with the Foundry Authoring extension and the Functions development server.

1.1 Prerequisites¶

macOS (Apple Silicon or Intel)
VS Code installed
Access to a Palantir Foundry instance
A Foundry code repository to be cloned

2. Installation and Environment Setup¶

2.1 Install Homebrew¶

Homebrew is the primary package manager for macOS developer tools.

Command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Post-Installation (Apple Silicon):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

2.2 Install Java 17¶

Foundry code repositories require Java 17 for Gradle builds.

Command:

brew install openjdk@17

2.3 Install Node.js via NVM¶

The Functions dev server requires Node.js 24.

1. Install NVM:

brew install nvm
mkdir -p ~/.nvm

2. Configure ~/.zshrc:

# NVM Configuration
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

3. Install Node 24:

source ~/.zshrc
nvm install 24
nvm use 24
nvm alias default 24

2.4 Configure Environment Variables¶

Foundry requires specific Java and Gradle environment variables.

1. Update ~/.zshrc:

# Java Configuration for Foundry
export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

# Foundry Gradle Trust Store
export ORG_GRADLE_PROJECT_trustStore="$JAVA_HOME/lib/security/cacerts"

⚠️ Important: On macOS with Homebrew, use the full path to libexec/openjdk.jdk/Contents/Home/. Using just /opt/homebrew/opt/openjdk@17 will result in missing file errors.

2. Apply and Verify:

source ~/.zshrc
echo $JAVA_HOME
java -version
ls $ORG_GRADLE_PROJECT_trustStore

2.5 Configure VS Code Inheritance¶

VS Code must be explicitly configured to access these variables when launched from the GUI.

1. Update Settings JSON: Open Cmd+Shift+P → "Preferences: Open Settings (JSON)" and add:

{
  "terminal.integrated.env.osx": {
    "JAVA_HOME": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home",
    "ORG_GRADLE_PROJECT_trustStore": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/lib/security/cacerts",
    "PATH": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/bin:${env:PATH}"
  }
}

2. Restart: Fully quit VS Code (Cmd+Q) and reopen.

💡 Alternative: You can avoid this configuration by always launching VS Code from the terminal using code ., which inherits your shell environment.

3. Authentication and Project Setup¶

3.1 Generate and Configure Bearer Token¶

Gradle requires a bearer token to download dependencies from your Foundry instance.

Generate Token: In Foundry, navigate to Settings → Tokens (or /workspace/settings/tokens) and generate a new token with appropriate scopes (repository read access at minimum).
Set Gradle Property: Create or edit the user-level Gradle properties file:
```
mkdir -p ~/.gradle
nano ~/.gradle/gradle.properties
```
Add: bearerToken=<paste-your-token-here>

⚠️ Security Note: Never commit your token to version control. Using the user-level ~/.gradle/gradle.properties keeps it safely outside your project directory.

3.2 Clone and Build Repository¶

1. Clone:

cd ~/Documents
git clone <your-repository-url>
cd <repository-name>

2. Initialize and Build:

code .
chmod +x ./gradlew
./gradlew build

4. Troubleshooting and Reference¶

4.1 Troubleshooting Guide¶

Issue	Potential Cause & Resolution
`unknown property 'bearerToken'`	Ensure `bearerToken=<token>` is set in `~/.gradle/gradle.properties`.
`JAVA_HOME not set`	Add `export JAVA_HOME=...` to `~/.zshrc` and run `source ~/.zshrc`. Restart VS Code.
`JAVA_HOME not set` (in GUI)	VS Code GUI apps don't inherit `~/.zshrc`. Use `settings.json` (Step 2.5) or run `launchctl setenv JAVA_HOME "..."` in terminal.
`unbound variable`	Ensure `ORG_GRADLE_PROJECT_trustStore` is exported in `~/.zshrc`.
`SSLInitializationException`	Path to `cacerts` is incorrect. Verify with `find /opt/homebrew/opt/openjdk@17 -name "cacerts"`.
`Token expired / 401`	Generate a new token (Step 3.1) and update `~/.gradle/gradle.properties`.
`Permission denied`	Run `chmod +x ./gradlew`.
`node: command not found`	Ensure Node is installed via NVM and `nvm alias default 24` was run.

4.2 Summary of Environment Variables¶

Final ~/.zshrc Configuration:

# Homebrew (Apple Silicon)
eval "$(/opt/homebrew/bin/brew shellenv)"

# NVM Configuration
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

# Java 17 for Foundry
export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

# Foundry Gradle Trust Store
export ORG_GRADLE_PROJECT_trustStore="$JAVA_HOME/lib/security/cacerts"

Final VS Code settings.json Configuration:

{
  "terminal.integrated.env.osx": {
    "JAVA_HOME": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home",
    "ORG_GRADLE_PROJECT_trustStore": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/lib/security/cacerts",
    "PATH": "/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/bin:${env:PATH}"
  }
}

4.3 Recommended VS Code Extensions¶

Palantir Foundry — Foundry authoring and Functions dev server
Gradle for Java — Gradle build support
Extension Pack for Java — Java language support
GitLens — Enhanced Git integration

5. Revision History¶

Version	Author	Description
1.0	Graham Thompson	Initial release